diff --git a/docs/API_REFERENCE_DYNAMIC.md b/docs/API_REFERENCE_DYNAMIC.md index 8ae4512..63833ca 100644 --- a/docs/API_REFERENCE_DYNAMIC.md +++ b/docs/API_REFERENCE_DYNAMIC.md @@ -1,6 +1,6 @@ # McRogueFace API Reference -*Generated on 2026-06-21 01:18:30* +*Generated on 2026-06-21 06:42:31* *This documentation was dynamically generated from the compiled module.* @@ -70,7 +70,7 @@ ## Functions -### `bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]` +### `bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]` Compute grid cells along a line using Bresenham's algorithm. @@ -130,7 +130,7 @@ Note: Get current performance metrics. -**Returns:** dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds) +**Returns:** dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds), grid_render_time (grid rendering time in ms), entity_render_time (entity rendering time in ms), fov_overlay_time (FOV overlay rendering time in ms), python_time (Python script execution time in ms), animation_time (animation processing time in ms), grid_cells_rendered (number of grid cells rendered this frame), entities_rendered (number of entities rendered this frame), total_entities (total entity count across all grids) ### `lock() -> _LockContext` @@ -402,11 +402,11 @@ 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)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `center`: Center position of the arc (Vector). - `color`: Arc fill color (Color). - `end_angle`: Ending angle in degrees (float). -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_pos`: Position in grid tile coordinates (Vector, only when parent is Grid). - `grid_size`: Size in grid tile coordinates (Vector, only when parent is Grid). @@ -414,10 +414,10 @@ Attributes: - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - `name`: Name for finding this element (str). -- `on_click`: Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_click`: Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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. @@ -583,14 +583,16 @@ Remove all children, keeping only the root node with original bounds. WARNING: I **Returns:** BSP: self, for method chaining -#### `find(pos: tuple[int, int]) -> BSPNode | None` +#### `find(pos: tuple[int, int] | list | Vector) -> BSPNode | None` Find the smallest (deepest) node containing the position. +Note: + **Arguments:** - `pos`: Position as (x, y) tuple, list, or Vector -**Returns:** BSPNode if found, None if position is outside bounds +**Returns:** BSPNode if found, None if position is outside bounds Also accepts two separate int arguments: find(x, y) #### `get_leaf(index: int) -> BSPNode` @@ -619,7 +621,7 @@ Split the root node once at the specified position. horizontal=True creates a ho **Returns:** BSP: self, for method chaining -#### `split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP` +#### `split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP` Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree. @@ -631,7 +633,7 @@ Recursively split to the specified depth. WARNING: Invalidates all existing BSPN **Returns:** BSP: self, for method chaining -#### `to_heightmap(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap` +#### `to_heightmap(size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap` Convert BSP node selection to a HeightMap. @@ -867,10 +869,10 @@ 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)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `fill_color`: Fill color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc. - `font_size`: Font size in points (int). Clamped to the range [0, 65535]. -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_pos`: Position in grid tile coordinates (Vector). Only valid when parent is a Grid. - `grid_size`: Size in grid tile coordinates (Vector). Only valid when parent is a Grid. @@ -879,10 +881,10 @@ Attributes: - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - `name`: Name for finding elements (str). -- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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 text outline border (float). Clamped to non-negative values. @@ -997,10 +999,10 @@ 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)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `center`: Center position of the circle (Vector). - `fill_color`: Fill color of the circle (Color). -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_pos`: Position in grid tile coordinates (Vector). Only meaningful when parent is a Grid. - `grid_size`: Size in grid tile coordinates (Vector). Only meaningful when parent is a Grid. @@ -1008,10 +1010,10 @@ Attributes: - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - `name`: Name for finding this element (str). -- `on_click`: Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: str, action: str). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_click`: Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState). +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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 in pixels (float). Use 0 for no outline. @@ -1207,7 +1209,7 @@ Interpolate between two colors based on HeightMap value within a range. Uses the **Returns:** self for method chaining -#### `apply_perspective(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None` +#### `apply_perspective(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None` Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves. @@ -1240,7 +1242,7 @@ Set a fixed color for cells where the HeightMap value falls within a range. **Returns:** self for method chaining -#### `at(pos) or (x: int, y: int) -> Color` +#### `at(pos: tuple | Vector) or (x: int, y: int) -> Color` Get the color at a cell position. @@ -1255,7 +1257,7 @@ Get the color at a cell position. Remove the perspective binding from this layer. -#### `draw_fov(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None` +#### `draw_fov(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None` Paint cells based on field-of-view visibility from a source position. @@ -1657,7 +1659,7 @@ Convert to HeightMap, optionally mapping values to floats. Base class for all drawable UI elements **Properties:** -- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). +- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. - `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable. - `z_index`: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed. @@ -1860,7 +1862,7 @@ Create and start an animation on this entity's property. Note: **Arguments:** -- `property`: Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index' +- `property`: Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index', 'sprite_offset_x', 'sprite_offset_y' - `target`: Target value - float, int, or list of int (for sprite frame sequences) - `duration`: Animation duration in seconds - `easing`: Easing function: Easing enum value, string name, or None for linear @@ -1871,7 +1873,7 @@ Note: **Returns:** Animation object for monitoring progress -**Raises:** ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index) Use 'draw_x'/'draw_y' to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations. +**Raises:** ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index, sprite_offset_x, sprite_offset_y) Use 'draw_x'/'draw_y' to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations. 'x' and 'y' are accepted as aliases for 'draw_x' and 'draw_y'. #### `at(x: int, y: int) -> GridPoint | None` @@ -1987,17 +1989,19 @@ Note: **Returns:** None Called automatically when the entity moves if the grid has FOV configured. -#### `visible_entities(fov=None, radius: int = None) -> list[Entity]` +#### `visible_entities(fov=None, radius: int = -1) -> list[Entity]` Get list of other entities visible from this entity's position. +Note: + **Arguments:** - `fov`: FOV algorithm to use (FOV enum or None to use grid.fov) -- `radius`: FOV radius (int or None to use grid.fov_radius) +- `radius`: FOV radius as int; omit or pass -1 to use the grid's default fov_radius **Returns:** List of Entity objects within field of view, excluding self -**Raises:** ValueError: If entity is not associated with a grid +**Raises:** ValueError: If entity is not associated with a grid radius does not accept None; omit the argument entirely to use the grid default. ### Entity3D @@ -2292,12 +2296,12 @@ 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)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `cache_subtree`: Cache the frame and all children to a render texture for performance (bool). Useful for complex static subtrees. - `children` *(read-only)*: UICollection of child drawable objects rendered on top of this frame (UICollection, read-only). - `clip_children`: Whether to clip child elements to the frame's bounds (bool). Enables render-texture mode when True. - `fill_color`: Fill color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc. -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_pos`: Position in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid. - `grid_size`: Size in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid. @@ -2306,10 +2310,10 @@ Attributes: - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - `name`: Name for finding elements (str). -- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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 in pixels (float). @@ -2412,13 +2416,13 @@ Keyword Args: **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)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `camera_rotation`: Rotation of grid contents around camera center in degrees (float). -- `center`: Camera center point in pixel coordinates (tuple). +- `center`: Camera center point in pixel coordinates (Vector). - `center_x`: Camera center X-coordinate in pixel space (float). - `center_y`: Camera center Y-coordinate in pixel space (float). - `fill_color`: Background fill color (Color). Drawn behind all tiles and entities. -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_data`: The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid. - `h`: Visible widget height (float). @@ -2427,9 +2431,9 @@ Keyword Args: - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - `name`: Name for finding elements (str). - `on_click`: Callable executed when object is clicked (Callable | None). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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. @@ -2437,7 +2441,7 @@ Keyword Args: - `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. -- `texture` *(read-only)*: Texture used for tile rendering (Texture | None, read-only). +- `texture` *(read-only)*: Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None. - `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. @@ -2532,13 +2536,13 @@ Keyword Args: **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)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `camera_rotation`: Rotation of grid contents around camera center in degrees (float). -- `center`: Camera center point in pixel coordinates (tuple). +- `center`: Camera center point in pixel coordinates (Vector). - `center_x`: Camera center X-coordinate in pixel space (float). - `center_y`: Camera center Y-coordinate in pixel space (float). - `fill_color`: Background fill color (Color). Drawn behind all tiles and entities. -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_data`: The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid. - `h`: Visible widget height (float). @@ -2547,9 +2551,9 @@ Keyword Args: - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - `name`: Name for finding elements (str). - `on_click`: Callable executed when object is clicked (Callable | None). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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. @@ -2557,7 +2561,7 @@ Keyword Args: - `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. -- `texture` *(read-only)*: Texture used for tile rendering (Texture | None, read-only). +- `texture` *(read-only)*: Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None. - `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. @@ -3427,10 +3431,10 @@ 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)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `color`: Line color as a Color object. - `end`: Ending point of the line as a Vector. -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_pos`: Position in grid tile coordinates (Vector, only when parent is Grid). - `grid_size`: Size in grid tile coordinates (Vector, only when parent is Grid). @@ -3438,10 +3442,10 @@ Attributes: - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - `name`: Name for finding this element. -- `on_click`: Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_click`: Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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. @@ -4264,8 +4268,8 @@ 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)). -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_pos`: Position in grid tile coordinates (Vector, only when parent is Grid). - `grid_size`: Size in grid tile coordinates (Vector, only when parent is Grid). @@ -4273,10 +4277,10 @@ Attributes: - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - `name`: Name for finding elements (str). -- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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. @@ -4508,7 +4512,7 @@ Set a tile index for cells where the HeightMap value falls within a range. **Returns:** self for method chaining -#### `at(pos) or (x: int, y: int) -> int` +#### `at(pos: tuple | Vector) or (x: int, y: int) -> int` Get the tile index at a cell position. Returns -1 if no tile is set. @@ -5169,7 +5173,7 @@ Keyword Args: **Properties:** - `bg_color`: Background clear color. -- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). +- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `camera_pos`: Camera position as (x, y, z) tuple. - `camera_target`: Camera look-at target as (x, y, z) tuple. - `cell_size`: World units per navigation grid cell. @@ -5182,15 +5186,15 @@ Keyword Args: - `fog_far`: Fog end distance. - `fog_near`: Fog start distance. - `fov`: Camera field of view in degrees. -- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). +- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain. - `grid_size`: Navigation grid dimensions as (width, depth) tuple. - `h`: Display height in pixels. - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. -- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). -- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. -- `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. +- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). +- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. +- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. +- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) 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]. - `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 Vector (x, y). diff --git a/docs/api-audit-2026-04.md b/docs/api-audit-2026-04.md index 7271aca..b835a28 100644 --- a/docs/api-audit-2026-04.md +++ b/docs/api-audit-2026-04.md @@ -660,8 +660,8 @@ NoiseSource(dimensions=2, algorithm='simplex', hurst=0.5, lacunarity=2.0, seed=N | Methods | Signature | |---------|-----------| -| `walk` | `() -> tuple` | -| `peek` | `() -> tuple` | +| `walk` | `() -> Vector` | +| `peek` | `() -> Vector` | Protocols: `len`, `bool`, iteration @@ -673,10 +673,10 @@ Protocols: `len`, `bool`, iteration | Methods | Signature | |---------|-----------| -| `distance` | `(x, y) -> float` | -| `path_from` | `(x, y) -> list` | -| `step_from` | `(x, y) -> tuple` | -| `to_heightmap` | `() -> HeightMap` | +| `distance` | `(pos) -> float \| None` | +| `path_from` | `(pos) -> AStarPath` | +| `step_from` | `(pos) -> Vector \| None` | +| `to_heightmap` | `(size=None, unreachable=-1.0) -> HeightMap` | --- diff --git a/docs/api_reference_dynamic.html b/docs/api_reference_dynamic.html index 4ef1d73..1a5482a 100644 --- a/docs/api_reference_dynamic.html +++ b/docs/api_reference_dynamic.html @@ -108,7 +108,7 @@

McRogueFace API Reference

-

Generated on 2026-06-21 01:18:30

+

Generated on 2026-06-21 06:42:31

This documentation was dynamically generated from the compiled module.

@@ -184,7 +184,7 @@

Functions

-

bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]

+

bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]

Compute grid cells along a line using Bresenham's algorithm. Note:

@@ -244,7 +244,7 @@ Note:

get_metrics() -> dict

Get current performance metrics.

-

Returns: dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds)

+

Returns: dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds), grid_render_time (grid rendering time in ms), entity_render_time (entity rendering time in ms), fov_overlay_time (FOV overlay rendering time in ms), python_time (Python script execution time in ms), animation_time (animation processing time in ms), grid_cells_rendered (number of grid cells rendered this frame), entities_rendered (number of entities rendered this frame), total_entities (total entity count across all grids)

@@ -524,11 +524,11 @@ 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)).
    • +
  • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
  • center: Center position of the arc (Vector).
  • color: Arc fill color (Color).
  • end_angle: Ending angle in degrees (float).
    • -
  • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
    • +
  • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
  • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
  • grid_pos: Position in grid tile coordinates (Vector, only when parent is Grid).
  • grid_size: Size in grid tile coordinates (Vector, only when parent is Grid).
    • @@ -536,10 +536,10 @@ Attributes:
  • hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
  • margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
  • name: Name for finding this element (str).
    • -
  • on_click: Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str).
    • -
  • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
    • -
  • 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.
    • +
  • on_click: Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
    • +
  • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
    • +
  • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
    • +
  • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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.
    • @@ -711,12 +711,14 @@ Example:
-
find(pos: tuple[int, int]) -> BSPNode | None
-

Find the smallest (deepest) node containing the position.

+
find(pos: tuple[int, int] | list | Vector) -> BSPNode | None
+

Find the smallest (deepest) node containing the position. + +Note:

pos: Position as (x, y) tuple, list, or Vector
-

Returns: BSPNode if found, None if position is outside bounds

+

Returns: BSPNode if found, None if position is outside bounds Also accepts two separate int arguments: find(x, y)

@@ -746,7 +748,7 @@ Example:
-
split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP
+
split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP

Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree.

depth: Maximum recursion depth (1-16). Creates up to 2^depth leaves.
@@ -758,7 +760,7 @@ Example:
-
to_heightmap(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap
+
to_heightmap(size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap

Convert BSP node selection to a HeightMap.

size: Output size (width, height). Default: bounds size.
@@ -1002,10 +1004,10 @@ 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)).
    • +
  • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
  • fill_color: Fill color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
  • font_size: Font size in points (int). Clamped to the range [0, 65535].
    • -
  • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
    • +
  • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
  • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
  • grid_pos: Position in grid tile coordinates (Vector). Only valid when parent is a Grid.
  • grid_size: Size in grid tile coordinates (Vector). Only valid when parent is a Grid.
    • @@ -1014,10 +1016,10 @@ Attributes:
  • hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
  • margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
  • name: Name for finding elements (str).
    • -
  • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
    • -
  • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
    • -
  • 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.
    • +
  • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
    • +
  • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
    • +
  • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
    • +
  • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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 text outline border (float). Clamped to non-negative values.
    • @@ -1134,10 +1136,10 @@ 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)).
      • +
    • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
    • center: Center position of the circle (Vector).
    • fill_color: Fill color of the circle (Color).
      • -
    • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
      • +
    • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
    • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
    • grid_pos: Position in grid tile coordinates (Vector). Only meaningful when parent is a Grid.
    • grid_size: Size in grid tile coordinates (Vector). Only meaningful when parent is a Grid.
      • @@ -1145,10 +1147,10 @@ Attributes:
    • hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
    • margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
    • name: Name for finding this element (str).
      • -
    • on_click: Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: str, action: str).
      • -
    • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
      • -
    • 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.
      • +
    • on_click: Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState).
      • +
    • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
      • +
    • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
      • +
    • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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 in pixels (float). Use 0 for no outline.
      • @@ -1348,7 +1350,7 @@ Example:
-
apply_perspective(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None
+
apply_perspective(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None

Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves.

entity: The entity whose perspective to track
@@ -1382,7 +1384,7 @@ Note:

-
at(pos) or (x: int, y: int) -> Color
+
at(pos: tuple | Vector) or (x: int, y: int) -> Color

Get the color at a cell position.

pos: Position as (x, y) tuple, list, or Vector; or pass x and y separately
@@ -1397,7 +1399,7 @@ Note:

-
draw_fov(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None
+
draw_fov(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None

Paint cells based on field-of-view visibility from a source position. Note:

@@ -1802,7 +1804,7 @@ Example:

Base class for all drawable UI elements

Properties:

    -
  • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
    • +
  • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
  • opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
  • visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
  • z_index: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
    • @@ -2015,7 +2017,7 @@ Attributes: Note:

    -
    property: Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index'
    +
    property: Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index', 'sprite_offset_x', 'sprite_offset_y'
    target: Target value - float, int, or list of int (for sprite frame sequences)
    duration: Animation duration in seconds
    easing: Easing function: Easing enum value, string name, or None for linear
    @@ -2025,7 +2027,7 @@ Note:

    conflict_mode: 'replace' (default), 'queue', or 'error' if property already animating

    Returns: Animation object for monitoring progress

    -

    Raises: ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index) Use 'draw_x'/'draw_y' to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations.

    +

    Raises: ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index, sprite_offset_x, sprite_offset_y) Use 'draw_x'/'draw_y' to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations. 'x' and 'y' are accepted as aliases for 'draw_x' and 'draw_y'.

@@ -2142,14 +2144,16 @@ Note:

-
visible_entities(fov=None, radius: int = None) -> list[Entity]
-

Get list of other entities visible from this entity's position.

+
visible_entities(fov=None, radius: int = -1) -> list[Entity]
+

Get list of other entities visible from this entity's position. + +Note:

fov: FOV algorithm to use (FOV enum or None to use grid.fov)
-
radius: FOV radius (int or None to use grid.fov_radius)
+
radius: FOV radius as int; omit or pass -1 to use the grid's default fov_radius

Returns: List of Entity objects within field of view, excluding self

-

Raises: ValueError: If entity is not associated with a grid

+

Raises: ValueError: If entity is not associated with a grid radius does not accept None; omit the argument entirely to use the grid default.

@@ -2468,12 +2472,12 @@ 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)).
    • +
  • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
  • cache_subtree: Cache the frame and all children to a render texture for performance (bool). Useful for complex static subtrees.
  • children (read-only): UICollection of child drawable objects rendered on top of this frame (UICollection, read-only).
  • clip_children: Whether to clip child elements to the frame's bounds (bool). Enables render-texture mode when True.
  • fill_color: Fill color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
    • -
  • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
    • +
  • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
  • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
  • grid_pos: Position in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid.
  • grid_size: Size in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid.
    • @@ -2482,10 +2486,10 @@ Attributes:
  • hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
  • margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
  • name: Name for finding elements (str).
    • -
  • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
    • -
  • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
    • -
  • 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.
    • +
  • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
    • +
  • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
    • +
  • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
    • +
  • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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 in pixels (float).
    • @@ -2590,13 +2594,13 @@ Keyword Args:

    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)).
      • +
    • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
    • camera_rotation: Rotation of grid contents around camera center in degrees (float).
      • -
    • center: Camera center point in pixel coordinates (tuple).
      • +
    • center: Camera center point in pixel coordinates (Vector).
    • center_x: Camera center X-coordinate in pixel space (float).
    • center_y: Camera center Y-coordinate in pixel space (float).
    • fill_color: Background fill color (Color). Drawn behind all tiles and entities.
      • -
    • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
      • +
    • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
    • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
    • grid_data: The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
    • h: Visible widget height (float).
      • @@ -2605,9 +2609,9 @@ Keyword Args:
    • margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
    • name: Name for finding elements (str).
    • on_click: Callable executed when object is clicked (Callable | None).
      • -
    • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
      • -
    • 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.
      • +
    • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
      • +
    • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
      • +
    • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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.
      • @@ -2615,7 +2619,7 @@ Keyword Args:
    • 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.
      • -
    • texture (read-only): Texture used for tile rendering (Texture | None, read-only).
      • +
    • texture (read-only): Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.
    • 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.
      • @@ -2712,13 +2716,13 @@ Keyword Args:

      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)).
        • +
      • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
      • camera_rotation: Rotation of grid contents around camera center in degrees (float).
        • -
      • center: Camera center point in pixel coordinates (tuple).
        • +
      • center: Camera center point in pixel coordinates (Vector).
      • center_x: Camera center X-coordinate in pixel space (float).
      • center_y: Camera center Y-coordinate in pixel space (float).
      • fill_color: Background fill color (Color). Drawn behind all tiles and entities.
        • -
      • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
        • +
      • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
      • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
      • grid_data: The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
      • h: Visible widget height (float).
        • @@ -2727,9 +2731,9 @@ Keyword Args:
      • margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
      • name: Name for finding elements (str).
      • on_click: Callable executed when object is clicked (Callable | None).
        • -
      • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
        • -
      • 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.
        • +
      • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
        • +
      • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
        • +
      • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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.
        • @@ -2737,7 +2741,7 @@ Keyword Args:
      • 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.
        • -
      • texture (read-only): Texture used for tile rendering (Texture | None, read-only).
        • +
      • texture (read-only): Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.
      • 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.
        • @@ -3625,10 +3629,10 @@ 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)).
          • +
        • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
        • color: Line color as a Color object.
        • end: Ending point of the line as a Vector.
          • -
        • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
          • +
        • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
        • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
        • grid_pos: Position in grid tile coordinates (Vector, only when parent is Grid).
        • grid_size: Size in grid tile coordinates (Vector, only when parent is Grid).
          • @@ -3636,10 +3640,10 @@ Attributes:
        • hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
        • margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
        • name: Name for finding this element.
          • -
        • on_click: Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str).
          • -
        • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
          • -
        • 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.
          • +
        • on_click: Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
          • +
        • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
          • +
        • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
          • +
        • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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.
          • @@ -4513,8 +4517,8 @@ 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)).
            • -
          • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
            • +
          • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
            • +
          • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
          • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
          • grid_pos: Position in grid tile coordinates (Vector, only when parent is Grid).
          • grid_size: Size in grid tile coordinates (Vector, only when parent is Grid).
            • @@ -4522,10 +4526,10 @@ Attributes:
          • hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
          • margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
          • name: Name for finding elements (str).
            • -
          • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
            • -
          • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
            • -
          • 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.
            • +
          • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
            • +
          • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
            • +
          • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
            • +
          • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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.
            • @@ -4760,7 +4764,7 @@ Note:

-
at(pos) or (x: int, y: int) -> int
+
at(pos: tuple | Vector) or (x: int, y: int) -> int

Get the tile index at a cell position. Returns -1 if no tile is set.

pos: Position as (x, y) tuple, list, or Vector; or pass x and y separately
@@ -5446,7 +5450,7 @@ Keyword Args:

Properties:

  • bg_color: Background clear color.
    • -
  • bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
    • +
  • bounds (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
  • camera_pos: Camera position as (x, y, z) tuple.
  • camera_target: Camera look-at target as (x, y, z) tuple.
  • cell_size: World units per navigation grid cell.
    • @@ -5459,15 +5463,15 @@ Keyword Args:
  • fog_far: Fog end distance.
  • fog_near: Fog start distance.
  • fov: Camera field of view in degrees.
    • -
  • global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
    • +
  • global_bounds (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
  • global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
  • grid_size: Navigation grid dimensions as (width, depth) tuple.
  • h: Display height in pixels.
  • hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
    • -
  • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
    • -
  • on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
    • -
  • 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.
    • +
  • on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
    • +
  • on_enter: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
    • +
  • on_exit: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
    • +
  • on_move: Callback for mouse movement within bounds. Called with (pos: Vector) 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].
  • 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 Vector (x, y).
    • diff --git a/docs/mcrfpy.3 b/docs/mcrfpy.3 index 87c731b..248bd4a 100644 --- a/docs/mcrfpy.3 +++ b/docs/mcrfpy.3 @@ -14,11 +14,11 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "MCRFPY" "3" "2026-06-21" "McRogueFace 0.2.7-prerelease-7drl2026-103-g39c2340" "" +.TH "MCRFPY" "3" "2026-06-21" "McRogueFace 0.2.7-prerelease-7drl2026-104-g5725a4f" "" .hy .SH McRogueFace API Reference .PP -\f[I]Generated on 2026-06-21 01:18:30\f[R] +\f[I]Generated on 2026-06-21 06:42:31\f[R] .PP \f[I]This documentation was dynamically generated from the compiled module.\f[R] @@ -148,7 +148,7 @@ Window .IP \[bu] 2 Constants .SS Functions -.SS \f[V]bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]\f[R] +.SS \f[V]bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]\f[R] .PP Compute grid cells along a line using Bresenham\[cq]s algorithm. .PP @@ -213,7 +213,14 @@ Get current performance metrics. frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), -current_frame (frame counter), runtime (total runtime in seconds) +current_frame (frame counter), runtime (total runtime in seconds), +grid_render_time (grid rendering time in ms), entity_render_time (entity +rendering time in ms), fov_overlay_time (FOV overlay rendering time in +ms), python_time (Python script execution time in ms), animation_time +(animation processing time in ms), grid_cells_rendered (number of grid +cells rendered this frame), entities_rendered (number of entities +rendered this frame), total_entities (total entity count across all +grids) .SS \f[V]lock() -> _LockContext\f[R] .PP Get a context manager for thread-safe UI updates from background @@ -478,14 +485,15 @@ 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. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). - \f[V]center\f[R]: Center position of the arc (Vector). - \f[V]color\f[R]: Arc fill color (Color). - \f[V]end_angle\f[R]: Ending angle in degrees (float). -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -505,16 +513,14 @@ Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - \f[V]name\f[R]: Name for finding this element (str). - \f[V]on_click\f[R]: Callable executed when arc is clicked. -Function receives (pos: Vector, button: str, action: str). +Function receives (pos: Vector, button: MouseButton, action: +InputState). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). @@ -701,14 +707,17 @@ Remove all children, keeping only the root node with original bounds. WARNING: Invalidates all existing BSPNode references from this tree. .PP \f[B]Returns:\f[R] BSP: self, for method chaining -.SS \f[V]find(pos: tuple[int, int]) -> BSPNode | None\f[R] +.SS \f[V]find(pos: tuple[int, int] | list | Vector) -> BSPNode | None\f[R] .PP Find the smallest (deepest) node containing the position. .PP +Note: +.PP \f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position as (x, y) tuple, list, or Vector .PP \f[B]Returns:\f[R] BSPNode if found, None if position is outside bounds +Also accepts two separate int arguments: find(x, y) .SS \f[V]get_leaf(index: int) -> BSPNode\f[R] .PP Get a leaf node by its index (0 to len(bsp)-1). @@ -739,7 +748,7 @@ horizontal=False creates a vertical divider, producing left/right rooms. Split coordinate (y for horizontal, x for vertical) .PP \f[B]Returns:\f[R] BSP: self, for method chaining -.SS \f[V]split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP\f[R] +.SS \f[V]split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP\f[R] .PP Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree. @@ -754,7 +763,7 @@ Default: 1.5. None for random. .PP \f[B]Returns:\f[R] BSP: self, for method chaining -.SS \f[V]to_heightmap(size: tuple[int, int] = None, select: str = \[aq]leaves\[aq], shrink: int = 0, value: float = 1.0) -> HeightMap\f[R] +.SS \f[V]to_heightmap(size: tuple[int, int] | None = None, select: str = \[aq]leaves\[aq], shrink: int = 0, value: float = 1.0) -> HeightMap\f[R] .PP Convert BSP node selection to a HeightMap. .PP @@ -967,16 +976,17 @@ 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. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). - \f[V]fill_color\f[R]: Fill color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use `fill_color.r', `fill_color.g', etc. - \f[V]font_size\f[R]: Font size in points (int). Clamped to the range [0, 65535]. -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -998,16 +1008,14 @@ Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - \f[V]name\f[R]: Name for finding elements (str). - \f[V]on_click\f[R]: Callable executed when object is clicked. -Function receives (pos: Vector, button: str, action: str). +Function receives (pos: Vector, button: MouseButton, action: +InputState). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). @@ -1144,13 +1152,14 @@ 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. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). - \f[V]center\f[R]: Center position of the circle (Vector). - \f[V]fill_color\f[R]: Fill color of the circle (Color). -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -1171,16 +1180,14 @@ Invalid for CENTER alignment (raises ValueError). - \f[V]name\f[R]: Name for finding this element (str). - \f[V]on_click\f[R]: Callable executed when circle is clicked (Callable | None). -Function receives (pos: Vector, button: str, action: str). +Function receives (pos: Vector, button: MouseButton, action: +InputState). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). @@ -1401,7 +1408,7 @@ layer dimensions) - \f[V]range\f[R]: Value range as (min, max) inclusive Color at range maximum .PP \f[B]Returns:\f[R] self for method chaining -.SS \f[V]apply_perspective(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None\f[R] +.SS \f[V]apply_perspective(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None\f[R] .PP Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves. @@ -1434,7 +1441,7 @@ layer dimensions) - \f[V]range\f[R]: Value range as (min, max) inclusive range .PP \f[B]Returns:\f[R] self for method chaining -.SS \f[V]at(pos) or (x: int, y: int) -> Color\f[R] +.SS \f[V]at(pos: tuple | Vector) or (x: int, y: int) -> Color\f[R] .PP Get the color at a cell position. .PP @@ -1447,7 +1454,7 @@ Vector; or pass x and y separately .SS \f[V]clear_perspective() -> None\f[R] .PP Remove the perspective binding from this layer. -.SS \f[V]draw_fov(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None\f[R] +.SS \f[V]draw_fov(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None\f[R] .PP Paint cells based on field-of-view visibility from a source position. .PP @@ -1813,7 +1820,8 @@ Base class for all drawable UI elements .PP \f[B]Properties:\f[R] - \f[V]on_click\f[R]: Callable executed when object is clicked. -Function receives (pos: Vector, button: str, action: str). +Function receives (pos: Vector, button: MouseButton, action: +InputState). - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. - \f[V]visible\f[R]: Whether the object is visible (bool). @@ -2058,23 +2066,25 @@ Note: .PP \f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to animate: `draw_x', `draw_y' (tile coords), `sprite_scale', -`sprite_index' - \f[V]target\f[R]: Target value - float, int, or list of -int (for sprite frame sequences) - \f[V]duration\f[R]: Animation -duration in seconds - \f[V]easing\f[R]: Easing function: Easing enum -value, string name, or None for linear - \f[V]delta\f[R]: If True, -target is relative to current value; if False, target is absolute - -\f[V]loop\f[R]: If True, animation repeats from start when it reaches -the end (default False) - \f[V]callback\f[R]: Optional callable invoked -when animation completes (not called for looping animations) - -\f[V]conflict_mode\f[R]: `replace' (default), `queue', or `error' if -property already animating +`sprite_index', `sprite_offset_x', `sprite_offset_y' - \f[V]target\f[R]: +Target value - float, int, or list of int (for sprite frame sequences) - +\f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]: +Easing function: Easing enum value, string name, or None for linear - +\f[V]delta\f[R]: If True, target is relative to current value; if False, +target is absolute - \f[V]loop\f[R]: If True, animation repeats from +start when it reaches the end (default False) - \f[V]callback\f[R]: +Optional callable invoked when animation completes (not called for +looping animations) - \f[V]conflict_mode\f[R]: `replace' (default), +`queue', or `error' if property already animating .PP \f[B]Returns:\f[R] Animation object for monitoring progress .PP \f[B]Raises:\f[R] ValueError: If property name is not valid for Entity -(draw_x, draw_y, sprite_scale, sprite_index) Use `draw_x'/`draw_y' to -animate tile coordinates for smooth movement between grid cells. +(draw_x, draw_y, sprite_scale, sprite_index, sprite_offset_x, +sprite_offset_y) Use `draw_x'/`draw_y' to animate tile coordinates for +smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations. +`x' and `y' are accepted as aliases for `draw_x' and `draw_y'. .SS \f[V]at(x: int, y: int) -> GridPoint | None\f[R] .PP Return the GridPoint at (x, y) if currently VISIBLE to this entity\[cq]s @@ -2184,18 +2194,22 @@ Note: .PP \f[B]Returns:\f[R] None Called automatically when the entity moves if the grid has FOV configured. -.SS \f[V]visible_entities(fov=None, radius: int = None) -> list[Entity]\f[R] +.SS \f[V]visible_entities(fov=None, radius: int = -1) -> list[Entity]\f[R] .PP Get list of other entities visible from this entity\[cq]s position. .PP +Note: +.PP \f[B]Arguments:\f[R] - \f[V]fov\f[R]: FOV algorithm to use (FOV enum or -None to use grid.fov) - \f[V]radius\f[R]: FOV radius (int or None to use -grid.fov_radius) +None to use grid.fov) - \f[V]radius\f[R]: FOV radius as int; omit or +pass -1 to use the grid\[cq]s default fov_radius .PP \f[B]Returns:\f[R] List of Entity objects within field of view, excluding self .PP \f[B]Raises:\f[R] ValueError: If entity is not associated with a grid +radius does not accept None; omit the argument entirely to use the grid +default. .SS Entity3D .PP Entity3D(pos=None, **kwargs) @@ -2469,8 +2483,9 @@ 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. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). - \f[V]cache_subtree\f[R]: Cache the frame and all children to a render texture for performance (bool). Useful for complex static subtrees. @@ -2483,9 +2498,9 @@ Enables render-texture mode when True. - \f[V]fill_color\f[R]: Fill color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use `fill_color.r', `fill_color.g', etc. -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -2506,16 +2521,14 @@ Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - \f[V]name\f[R]: Name for finding elements (str). - \f[V]on_click\f[R]: Callable executed when object is clicked. -Function receives (pos: Vector, button: str, action: str). +Function receives (pos: Vector, button: MouseButton, action: +InputState). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). @@ -2643,18 +2656,19 @@ 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. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). - \f[V]camera_rotation\f[R]: Rotation of grid contents around camera center in degrees (float). -- \f[V]center\f[R]: Camera center point in pixel coordinates (tuple). +- \f[V]center\f[R]: Camera center point in pixel coordinates (Vector). - \f[V]center_x\f[R]: Camera center X-coordinate in pixel space (float). - \f[V]center_y\f[R]: Camera center Y-coordinate in pixel space (float). - \f[V]fill_color\f[R]: Background fill color (Color). Drawn behind all tiles and entities. -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -2675,14 +2689,11 @@ Invalid for CENTER alignment (raises ValueError). - \f[V]on_click\f[R]: Callable executed when object is clicked (Callable | None). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). @@ -2706,7 +2717,8 @@ Animatable property. When set, the drawable is rendered through the shader program. Set to None to disable shader effects. - \f[V]texture\f[R] \f[I](read-only)\f[R]: Texture used for tile -rendering (Texture | None, read-only). +rendering (None, read-only). +Texture return is not yet implemented; always returns None. - \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. @@ -2809,18 +2821,19 @@ 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. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). - \f[V]camera_rotation\f[R]: Rotation of grid contents around camera center in degrees (float). -- \f[V]center\f[R]: Camera center point in pixel coordinates (tuple). +- \f[V]center\f[R]: Camera center point in pixel coordinates (Vector). - \f[V]center_x\f[R]: Camera center X-coordinate in pixel space (float). - \f[V]center_y\f[R]: Camera center Y-coordinate in pixel space (float). - \f[V]fill_color\f[R]: Background fill color (Color). Drawn behind all tiles and entities. -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -2841,14 +2854,11 @@ Invalid for CENTER alignment (raises ValueError). - \f[V]on_click\f[R]: Callable executed when object is clicked (Callable | None). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). @@ -2872,7 +2882,8 @@ Animatable property. When set, the drawable is rendered through the shader program. Set to None to disable shader effects. - \f[V]texture\f[R] \f[I](read-only)\f[R]: Texture used for tile -rendering (Texture | None, read-only). +rendering (None, read-only). +Texture return is not yet implemented; always returns None. - \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. @@ -3666,13 +3677,14 @@ 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. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). - \f[V]color\f[R]: Line color as a Color object. - \f[V]end\f[R]: Ending point of the line as a Vector. -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -3692,16 +3704,14 @@ Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - \f[V]name\f[R]: Name for finding this element. - \f[V]on_click\f[R]: Callable executed when line is clicked. -Function receives (pos: Vector, button: str, action: str). +Function receives (pos: Vector, button: MouseButton, action: +InputState). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). @@ -4527,11 +4537,12 @@ 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. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -4551,16 +4562,14 @@ Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError). - \f[V]name\f[R]: Name for finding elements (str). - \f[V]on_click\f[R]: Callable executed when object is clicked. -Function receives (pos: Vector, button: str, action: str). +Function receives (pos: Vector, button: MouseButton, action: +InputState). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). @@ -4837,7 +4846,7 @@ layer dimensions) - \f[V]range\f[R]: Value range as (min, max) inclusive - \f[V]tile\f[R]: Tile index to set for cells in range .PP \f[B]Returns:\f[R] self for method chaining -.SS \f[V]at(pos) or (x: int, y: int) -> int\f[R] +.SS \f[V]at(pos: tuple | Vector) or (x: int, y: int) -> int\f[R] .PP Get the tile index at a cell position. Returns -1 if no tile is set. @@ -5459,8 +5468,9 @@ Default: 10 fog_far (float): Fog end distance. Default: 100 .PP \f[B]Properties:\f[R] - \f[V]bg_color\f[R]: Background clear color. -- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box +(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), +Vector(width, height)). - \f[V]camera_pos\f[R]: Camera position as (x, y, z) tuple. - \f[V]camera_target\f[R]: Camera look-at target as (x, y, z) tuple. - \f[V]cell_size\f[R]: World units per navigation grid cell. @@ -5477,9 +5487,9 @@ Use append/remove to modify. - \f[V]fog_far\f[R]: Fog end distance. - \f[V]fog_near\f[R]: Fog start distance. - \f[V]fov\f[R]: Camera field of view in degrees. -- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors -in screen coordinates. -Returns (Vector(x, y), Vector(width, height)). +- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding +box in screen coordinates (tuple, read-only) as a (pos, size) pair of +Vectors: (Vector(x, y), Vector(width, height)). - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen position (read-only). Calculates absolute position by walking up the parent chain. @@ -5490,16 +5500,14 @@ tuple. over this element (read-only). Updated automatically by the engine during mouse movement. - \f[V]on_click\f[R]: Callable executed when object is clicked. -Function receives (pos: Vector, button: str, action: str). +Function receives (pos: Vector, button: MouseButton, action: +InputState). - \f[V]on_enter\f[R]: Callback for mouse enter events. -Called with (pos: Vector, button: str, action: str) when mouse enters -this element\[cq]s bounds. +Called with (pos: Vector) when mouse enters this element\[cq]s bounds. - \f[V]on_exit\f[R]: Callback for mouse exit events. -Called with (pos: Vector, button: str, action: str) when mouse leaves -this element\[cq]s bounds. +Called with (pos: Vector) when mouse leaves this element\[cq]s bounds. - \f[V]on_move\f[R]: Callback for mouse movement within bounds. -Called with (pos: Vector, button: str, action: str) for each mouse -movement while inside. +Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast. - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque). diff --git a/src/GridLayers.cpp b/src/GridLayers.cpp index c1d3586..4dc9022 100644 --- a/src/GridLayers.cpp +++ b/src/GridLayers.cpp @@ -701,7 +701,7 @@ void TileLayer::render(sf::RenderTarget& target, PyMethodDef PyGridLayerAPI::ColorLayer_methods[] = { {"at", (PyCFunction)PyGridLayerAPI::ColorLayer_at, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(ColorLayer, at, - MCRF_SIG("(pos) or (x: int, y: int)", "Color"), + MCRF_SIG("(pos: tuple | Vector) or (x: int, y: int)", "Color"), MCRF_DESC("Get the color at a cell position.") MCRF_ARGS_START MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector; or pass x and y separately") @@ -735,7 +735,7 @@ PyMethodDef PyGridLayerAPI::ColorLayer_methods[] = { )}, {"draw_fov", (PyCFunction)PyGridLayerAPI::ColorLayer_draw_fov, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(ColorLayer, draw_fov, - MCRF_SIG("(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None)", "None"), + MCRF_SIG("(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None)", "None"), MCRF_DESC("Paint cells based on field-of-view visibility from a source position.") MCRF_ARGS_START MCRF_ARG("source", "FOV origin as (x, y)") @@ -748,7 +748,7 @@ PyMethodDef PyGridLayerAPI::ColorLayer_methods[] = { )}, {"apply_perspective", (PyCFunction)PyGridLayerAPI::ColorLayer_apply_perspective, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(ColorLayer, apply_perspective, - MCRF_SIG("(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None)", "None"), + MCRF_SIG("(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None)", "None"), MCRF_DESC("Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves.") MCRF_ARGS_START MCRF_ARG("entity", "The entity whose perspective to track") @@ -1881,7 +1881,7 @@ PyObject* PyGridLayerAPI::ColorLayer_repr(PyColorLayerObject* self) { PyMethodDef PyGridLayerAPI::TileLayer_methods[] = { {"at", (PyCFunction)PyGridLayerAPI::TileLayer_at, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(TileLayer, at, - MCRF_SIG("(pos) or (x: int, y: int)", "int"), + MCRF_SIG("(pos: tuple | Vector) or (x: int, y: int)", "int"), MCRF_DESC("Get the tile index at a cell position. Returns -1 if no tile is set.") MCRF_ARGS_START MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector; or pass x and y separately") diff --git a/src/McRFPy_API.cpp b/src/McRFPy_API.cpp index 4829692..7a87048 100644 --- a/src/McRFPy_API.cpp +++ b/src/McRFPy_API.cpp @@ -306,7 +306,7 @@ static PyMethodDef mcrfpyMethods[] = { MCRF_METHOD(mcrfpy, get_metrics, MCRF_SIG("()", "dict"), MCRF_DESC("Get current performance metrics."), - MCRF_RETURNS("dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds)") + MCRF_RETURNS("dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds), grid_render_time (grid rendering time in ms), entity_render_time (entity rendering time in ms), fov_overlay_time (FOV overlay rendering time in ms), python_time (Python script execution time in ms), animation_time (animation processing time in ms), grid_cells_rendered (number of grid cells rendered this frame), entities_rendered (number of entities rendered this frame), total_entities (total entity count across all grids)") )}, {"set_dev_console", McRFPy_API::_setDevConsole, METH_VARARGS, @@ -369,7 +369,7 @@ static PyMethodDef mcrfpyMethods[] = { // #215: Bresenham line algorithm (replaces mcrfpy.libtcod.line) {"bresenham", (PyCFunction)McRFPy_API::_bresenham, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(mcrfpy, bresenham, - MCRF_SIG("(start, end, *, include_start=True, include_end=True)", "list[tuple[int, int]]"), + MCRF_SIG("(start, end, include_start=True, include_end=True)", "list[tuple[int, int]]"), MCRF_DESC("Compute grid cells along a line using Bresenham's algorithm."), MCRF_ARGS_START MCRF_ARG("start", "(x, y) tuple or Vector - starting point") diff --git a/src/McRFPy_Automation.cpp b/src/McRFPy_Automation.cpp index 850b7f4..bf5de2e 100644 --- a/src/McRFPy_Automation.cpp +++ b/src/McRFPy_Automation.cpp @@ -853,20 +853,22 @@ static PyMethodDef automationMethods[] = { {"position", McRFPy_Automation::_position, METH_NOARGS, MCRF_METHOD(automation, position, MCRF_SIG("()", "Vector"), - MCRF_DESC("Get the current mouse position as a Vector.") + MCRF_DESC("Get the current mouse position as a Vector."), MCRF_RETURNS("Vector: current mouse position in screen coordinates") )}, {"size", McRFPy_Automation::_size, METH_NOARGS, MCRF_METHOD(automation, size, MCRF_SIG("()", "Vector"), - MCRF_DESC("Get the current screen (render target) size as a Vector.") + MCRF_DESC("Get the current screen (render target) size as a Vector."), MCRF_RETURNS("Vector: screen width and height in pixels") )}, {"onScreen", (PyCFunction)McRFPy_Automation::_onScreen, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(automation, onScreen, - MCRF_SIG("(pos: tuple | list | Vector)", "bool"), + MCRF_SIG("(x: int, y: int) or (pos: tuple | list | Vector)", "bool"), MCRF_DESC("Check if a position is within the screen bounds."), MCRF_ARGS_START + MCRF_ARG("x", "X coordinate (int), when passing two separate int arguments") + MCRF_ARG("y", "Y coordinate (int), when passing two separate int arguments") MCRF_ARG("pos", "Position as (x, y) tuple, [x, y] list, or Vector") MCRF_RETURNS("True if the position is on screen, False otherwise") )}, @@ -951,6 +953,7 @@ static PyMethodDef automationMethods[] = { MCRF_ARGS_START MCRF_ARG("clicks", "Number of scroll steps (positive = up, negative = down)") MCRF_ARG("pos", "Position as (x, y) tuple, [x, y] list, Vector, or None for current position") + MCRF_NOTE("The x-coordinate of pos is currently unused; only the y-coordinate is applied to the scroll event position.") )}, {"mouseDown", (PyCFunction)McRFPy_Automation::_mouseDown, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(automation, mouseDown, diff --git a/src/PyBSP.cpp b/src/PyBSP.cpp index 8380838..f30f057 100644 --- a/src/PyBSP.cpp +++ b/src/PyBSP.cpp @@ -342,7 +342,7 @@ PyMethodDef PyBSP::methods[] = { )}, {"split_recursive", (PyCFunction)PyBSP::split_recursive, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(BSP, split_recursive, - MCRF_SIG("(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None)", "BSP"), + MCRF_SIG("(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None)", "BSP"), MCRF_DESC("Recursively split to the specified depth. " "WARNING: Invalidates all existing BSPNode references from this tree."), MCRF_ARGS_START @@ -376,15 +376,16 @@ PyMethodDef PyBSP::methods[] = { )}, {"find", (PyCFunction)PyBSP::find, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(BSP, find, - MCRF_SIG("(pos: tuple[int, int])", "BSPNode | None"), + MCRF_SIG("(pos: tuple[int, int] | list | Vector)", "BSPNode | None"), MCRF_DESC("Find the smallest (deepest) node containing the position."), MCRF_ARGS_START MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector") MCRF_RETURNS("BSPNode if found, None if position is outside bounds") + MCRF_NOTE("Also accepts two separate int arguments: find(x, y)") )}, {"to_heightmap", (PyCFunction)PyBSP::to_heightmap, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(BSP, to_heightmap, - MCRF_SIG("(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0)", "HeightMap"), + MCRF_SIG("(size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0)", "HeightMap"), MCRF_DESC("Convert BSP node selection to a HeightMap."), MCRF_ARGS_START MCRF_ARG("size", "Output size (width, height). Default: bounds size.") @@ -1055,11 +1056,12 @@ PyGetSetDef PyBSPNode::getsetters[] = { PyMethodDef PyBSPNode::methods[] = { {"contains", (PyCFunction)PyBSPNode::contains, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(BSPNode, contains, - MCRF_SIG("(pos: tuple[int, int])", "bool"), + MCRF_SIG("(pos: tuple[int, int] | list | Vector)", "bool"), MCRF_DESC("Check if position is inside this node's bounds."), MCRF_ARGS_START MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector") MCRF_RETURNS("bool: True if position is inside bounds") + MCRF_NOTE("Also accepts two separate int arguments: contains(x, y)") )}, {"center", (PyCFunction)PyBSPNode::center, METH_NOARGS, MCRF_METHOD(BSPNode, center, diff --git a/src/PyDrawable.cpp b/src/PyDrawable.cpp index 849409f..929edcf 100644 --- a/src/PyDrawable.cpp +++ b/src/PyDrawable.cpp @@ -104,7 +104,7 @@ static PyGetSetDef PyDrawable_getsetters[] = { {"on_click", (getter)PyDrawable_get_click, (setter)PyDrawable_set_click, MCRF_PROPERTY(on_click, "Callable executed when object is clicked. " - "Function receives (pos: Vector, button: str, action: str)." + "Function receives (pos: Vector, button: MouseButton, action: InputState)." ), NULL}, {"z_index", (getter)PyDrawable_get_z_index, (setter)PyDrawable_set_z_index, MCRF_PROPERTY(z_index, diff --git a/src/PyLock.cpp b/src/PyLock.cpp index 6ed342d..460d401 100644 --- a/src/PyLock.cpp +++ b/src/PyLock.cpp @@ -21,8 +21,12 @@ static PyMethodDef PyLockContext_methods[] = { )}, {"__exit__", (PyCFunction)PyLockContext_exit, METH_VARARGS, MCRF_METHOD(LockContext, __exit__, - MCRF_SIG("(exc_type, exc_val, exc_tb)", "bool"), + MCRF_SIG("(exc_type, exc_val, exc_tb)", "bool | None"), MCRF_DESC("Release the frame lock. Does not suppress exceptions."), + MCRF_ARGS_START + MCRF_ARG("exc_type", "Exception type, or None if no exception occurred") + MCRF_ARG("exc_val", "Exception value, or None if no exception occurred") + MCRF_ARG("exc_tb", "Exception traceback, or None if no exception occurred") MCRF_RETURNS("False, so any active exception propagates normally") )}, {NULL} diff --git a/src/PyUniformCollection.cpp b/src/PyUniformCollection.cpp index ca9a382..89c53d1 100644 --- a/src/PyUniformCollection.cpp +++ b/src/PyUniformCollection.cpp @@ -121,7 +121,7 @@ PyMethodDef PyUniformCollectionType::methods[] = { MCRF_METHOD(UniformCollection, values, MCRF_SIG("()", "list"), MCRF_DESC("Return a list of all uniform values in this collection.") - MCRF_RETURNS("list of float or tuple: the values of all uniforms currently set") + MCRF_RETURNS("list[float | tuple | None]: values of all uniforms; PropertyBinding/CallableBinding entries are None if not yet evaluable") )}, {"items", (PyCFunction)PyUniformCollectionType::items, METH_NOARGS, MCRF_METHOD(UniformCollection, items, diff --git a/src/UIArc.cpp b/src/UIArc.cpp index 780caf1..fd85fce 100644 --- a/src/UIArc.cpp +++ b/src/UIArc.cpp @@ -506,7 +506,7 @@ PyGetSetDef UIArc::getsetters[] = { {"thickness", (getter)UIArc::get_thickness, (setter)UIArc::set_thickness, MCRF_PROPERTY(thickness, "Line thickness in pixels (float)."), NULL}, {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, - MCRF_PROPERTY(on_click, "Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str)."), (void*)PyObjectsEnum::UIARC}, + MCRF_PROPERTY(on_click, "Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState)."), (void*)PyObjectsEnum::UIARC}, {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, MCRF_PROPERTY(z_index, "Z-order for rendering (int, lower values rendered first)."), (void*)PyObjectsEnum::UIARC}, {"name", (getter)UIDrawable::get_name, (setter)UIDrawable::set_name, diff --git a/src/UIBase.h b/src/UIBase.h index 06d1ed3..3742883 100644 --- a/src/UIBase.h +++ b/src/UIBase.h @@ -259,21 +259,21 @@ static int UIDrawable_set_opacity(T* self, PyObject* value, void* closure) ), (void*)type_enum}, \ {"bounds", (getter)UIDrawable::get_bounds_py, NULL, \ MCRF_PROPERTY(bounds, \ - "Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height))." \ + "Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height))." \ ), (void*)type_enum}, \ {"global_bounds", (getter)UIDrawable::get_global_bounds_py, NULL, \ MCRF_PROPERTY(global_bounds, \ - "Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height))." \ + "Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height))." \ ), (void*)type_enum}, \ {"on_enter", (getter)UIDrawable::get_on_enter, (setter)UIDrawable::set_on_enter, \ MCRF_PROPERTY(on_enter, \ "Callback for mouse enter events. " \ - "Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds." \ + "Called with (pos: Vector) when mouse enters this element's bounds." \ ), (void*)type_enum}, \ {"on_exit", (getter)UIDrawable::get_on_exit, (setter)UIDrawable::set_on_exit, \ MCRF_PROPERTY(on_exit, \ "Callback for mouse exit events. " \ - "Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds." \ + "Called with (pos: Vector) when mouse leaves this element's bounds." \ ), (void*)type_enum}, \ {"hovered", (getter)UIDrawable::get_hovered, NULL, \ MCRF_PROPERTY(hovered, \ @@ -283,7 +283,7 @@ static int UIDrawable_set_opacity(T* self, PyObject* value, void* closure) {"on_move", (getter)UIDrawable::get_on_move, (setter)UIDrawable::set_on_move, \ MCRF_PROPERTY(on_move, \ "Callback for mouse movement within bounds. " \ - "Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. " \ + "Called with (pos: Vector) for each mouse movement while inside. " \ "Performance note: Called frequently during movement - keep handlers fast." \ ), (void*)type_enum} diff --git a/src/UICaption.cpp b/src/UICaption.cpp index 21247b8..d803721 100644 --- a/src/UICaption.cpp +++ b/src/UICaption.cpp @@ -421,7 +421,7 @@ PyGetSetDef UICaption::getsetters[] = { {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, MCRF_PROPERTY(on_click, "Callable executed when object is clicked. " - "Function receives (pos: Vector, button: str, action: str)." + "Function receives (pos: Vector, button: MouseButton, action: InputState)." ), (void*)PyObjectsEnum::UICAPTION}, {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, MCRF_PROPERTY(z_index, diff --git a/src/UICircle.cpp b/src/UICircle.cpp index d677b6c..b9f2ab0 100644 --- a/src/UICircle.cpp +++ b/src/UICircle.cpp @@ -450,7 +450,7 @@ PyGetSetDef UICircle::getsetters[] = { {"outline", (getter)UICircle::get_outline, (setter)UICircle::set_outline, MCRF_PROPERTY(outline, "Outline thickness in pixels (float). Use 0 for no outline."), NULL}, {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, - MCRF_PROPERTY(on_click, "Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: str, action: str)."), (void*)PyObjectsEnum::UICIRCLE}, + MCRF_PROPERTY(on_click, "Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState)."), (void*)PyObjectsEnum::UICIRCLE}, {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, MCRF_PROPERTY(z_index, "Z-order for rendering (int). Lower values are rendered first."), (void*)PyObjectsEnum::UICIRCLE}, {"name", (getter)UIDrawable::get_name, (setter)UIDrawable::set_name, diff --git a/src/UICollection.cpp b/src/UICollection.cpp index 778a3fa..87a4f2d 100644 --- a/src/UICollection.cpp +++ b/src/UICollection.cpp @@ -1056,7 +1056,7 @@ PyMethodDef UICollection::methods[] = { )}, {"extend", (PyCFunction)UICollection::extend, METH_O, MCRF_METHOD(UICollection, extend, - MCRF_SIG("(iterable)", "None"), + MCRF_SIG("(iterable: Iterable[Drawable])", "None"), MCRF_DESC("Add all elements from an iterable to the collection.") MCRF_ARGS_START MCRF_ARG("iterable", "Iterable of Drawable objects to add") diff --git a/src/UIEntity.cpp b/src/UIEntity.cpp index 27523e6..53d397c 100644 --- a/src/UIEntity.cpp +++ b/src/UIEntity.cpp @@ -1394,13 +1394,14 @@ PyMethodDef UIEntity::methods[] = { )}, {"visible_entities", (PyCFunction)UIEntity::visible_entities, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Entity, visible_entities, - MCRF_SIG("(fov=None, radius: int = None)", "list[Entity]"), + MCRF_SIG("(fov=None, radius: int = -1)", "list[Entity]"), MCRF_DESC("Get list of other entities visible from this entity's position."), MCRF_ARGS_START MCRF_ARG("fov", "FOV algorithm to use (FOV enum or None to use grid.fov)") - MCRF_ARG("radius", "FOV radius (int or None to use grid.fov_radius)") + MCRF_ARG("radius", "FOV radius as int; omit or pass -1 to use the grid's default fov_radius") MCRF_RETURNS("List of Entity objects within field of view, excluding self") MCRF_RAISES("ValueError", "If entity is not associated with a grid") + MCRF_NOTE("radius does not accept None; omit the argument entirely to use the grid default.") )}, {NULL, NULL, 0, NULL} }; @@ -1735,7 +1736,7 @@ PyMethodDef UIEntity_all_methods[] = { MCRF_SIG("(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace')", "Animation"), MCRF_DESC("Create and start an animation on this entity's property."), MCRF_ARGS_START - MCRF_ARG("property", "Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index'") + MCRF_ARG("property", "Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index', 'sprite_offset_x', 'sprite_offset_y'") MCRF_ARG("target", "Target value - float, int, or list of int (for sprite frame sequences)") MCRF_ARG("duration", "Animation duration in seconds") MCRF_ARG("easing", "Easing function: Easing enum value, string name, or None for linear") @@ -1744,9 +1745,10 @@ PyMethodDef UIEntity_all_methods[] = { MCRF_ARG("callback", "Optional callable invoked when animation completes (not called for looping animations)") MCRF_ARG("conflict_mode", "'replace' (default), 'queue', or 'error' if property already animating") MCRF_RETURNS("Animation object for monitoring progress") - MCRF_RAISES("ValueError", "If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index)") + MCRF_RAISES("ValueError", "If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index, sprite_offset_x, sprite_offset_y)") MCRF_NOTE("Use 'draw_x'/'draw_y' to animate tile coordinates for smooth movement between grid cells. " - "Use list target with loop=True for repeating sprite frame animations.") + "Use list target with loop=True for repeating sprite frame animations. " + "'x' and 'y' are accepted as aliases for 'draw_x' and 'draw_y'.") )}, {"at", (PyCFunction)UIEntity::at, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Entity, at, @@ -1802,13 +1804,14 @@ PyMethodDef UIEntity_all_methods[] = { )}, {"visible_entities", (PyCFunction)UIEntity::visible_entities, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Entity, visible_entities, - MCRF_SIG("(fov=None, radius: int = None)", "list[Entity]"), + MCRF_SIG("(fov=None, radius: int = -1)", "list[Entity]"), MCRF_DESC("Get list of other entities visible from this entity's position."), MCRF_ARGS_START MCRF_ARG("fov", "FOV algorithm to use (FOV enum or None to use grid.fov)") - MCRF_ARG("radius", "FOV radius (int or None to use grid.fov_radius)") + MCRF_ARG("radius", "FOV radius as int; omit or pass -1 to use the grid's default fov_radius") MCRF_RETURNS("List of Entity objects within field of view, excluding self") MCRF_RAISES("ValueError", "If entity is not associated with a grid") + MCRF_NOTE("radius does not accept None; omit the argument entirely to use the grid default.") )}, // #296 - Label methods {"add_label", (PyCFunction)UIEntity::py_add_label, METH_O, diff --git a/src/UIEntityCollection.cpp b/src/UIEntityCollection.cpp index 6c04ea2..7ea2509 100644 --- a/src/UIEntityCollection.cpp +++ b/src/UIEntityCollection.cpp @@ -974,6 +974,7 @@ PyMethodDef UIEntityCollection::methods[] = { MCRF_ARG("iterable", "Iterable of Entity objects to add") MCRF_RETURNS("None") MCRF_RAISES("TypeError", "If any item is not an Entity object") + MCRF_RAISES("RuntimeError", "If an Entity object in the iterable has invalid (null) internal state") )}, {"insert", (PyCFunction)UIEntityCollection::insert, METH_VARARGS, MCRF_METHOD(EntityCollection, insert, @@ -1021,7 +1022,7 @@ PyMethodDef UIEntityCollection::methods[] = { )}, {"find", (PyCFunction)UIEntityCollection::find, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(EntityCollection, find, - MCRF_SIG("(name: str)", "Entity | list | None"), + MCRF_SIG("(name: str)", "Entity | list[Entity] | None"), MCRF_DESC("Find entities by name. Returns a single entity for exact matches or a list for wildcard patterns."), MCRF_ARGS_START MCRF_ARG("name", "Name to search for; supports wildcards: 'exact', 'prefix*', '*suffix', '*substring*'") diff --git a/src/UIFrame.cpp b/src/UIFrame.cpp index 22738d5..9e5da4f 100644 --- a/src/UIFrame.cpp +++ b/src/UIFrame.cpp @@ -553,7 +553,7 @@ PyGetSetDef UIFrame::getsetters[] = { {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, MCRF_PROPERTY(on_click, "Callable executed when object is clicked. " - "Function receives (pos: Vector, button: str, action: str)." + "Function receives (pos: Vector, button: MouseButton, action: InputState)." ), (void*)PyObjectsEnum::UIFRAME}, {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, MCRF_PROPERTY(z_index, diff --git a/src/UIGridPoint.cpp b/src/UIGridPoint.cpp index b2aa80d..bc67d14 100644 --- a/src/UIGridPoint.cpp +++ b/src/UIGridPoint.cpp @@ -143,7 +143,7 @@ PyGetSetDef UIGridPoint::getsetters[] = { {"entities", (getter)UIGridPoint::get_entities, NULL, MCRF_PROPERTY(entities, "List of Entity objects currently occupying this cell (list, read-only)."), NULL}, {"grid_pos", (getter)UIGridPoint::get_grid_pos, NULL, - MCRF_PROPERTY(grid_pos, "Grid coordinates as (x, y) tuple (read-only)."), NULL}, + MCRF_PROPERTY(grid_pos, "Grid coordinates as an (x, y) position (tuple, read-only)."), NULL}, {NULL} /* Sentinel */ }; diff --git a/src/UIGridPyMethods.cpp b/src/UIGridPyMethods.cpp index 8937da5..9b6b783 100644 --- a/src/UIGridPyMethods.cpp +++ b/src/UIGridPyMethods.cpp @@ -899,44 +899,51 @@ PyMethodDef UIGrid::methods[] = { MCRF_ARG("y", "Row index (0-based)") MCRF_RETURNS("GridPoint: the cell at the given position") MCRF_RAISES("IndexError", "If x or y is out of range") + MCRF_NOTE("Also accepts a single positional tuple/list/Vector: at((x, y)) or at(vec), or keyword form: at(pos=(x, y)).") )}, {"compute_fov", (PyCFunction)UIGrid::py_compute_fov, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Grid, compute_fov, - MCRF_SIG("(pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC)", "None"), + MCRF_SIG("(pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC)", "None"), MCRF_DESC("Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility."), MCRF_ARGS_START MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector") MCRF_ARG("radius", "Maximum view distance (0 = unlimited)") MCRF_ARG("light_walls", "Whether walls are lit when visible") - MCRF_ARG("algorithm", "FOV algorithm to use (FOV_BASIC, FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8)") + MCRF_ARG("algorithm", "FOV algorithm to use (FOV.BASIC, FOV.DIAMOND, FOV.SHADOW, FOV.PERMISSIVE_0-8)") + MCRF_RETURNS("None") )}, {"is_in_fov", (PyCFunction)UIGrid::py_is_in_fov, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Grid, is_in_fov, - MCRF_SIG("(pos)", "bool"), + MCRF_SIG("(x: int, y: int)", "bool"), MCRF_DESC("Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility."), MCRF_ARGS_START - MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector") + MCRF_ARG("x", "Column index (0-based)") + MCRF_ARG("y", "Row index (0-based)") MCRF_RETURNS("True if the cell is visible, False otherwise") + MCRF_NOTE("Also accepts a single positional tuple/list/Vector: is_in_fov((x, y)) or is_in_fov(vec), or keyword form: is_in_fov(pos=(x, y)).") )}, {"find_path", (PyCFunction)UIGridPathfinding::Grid_find_path, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Grid, find_path, - MCRF_SIG("(start, end, diagonal_cost: float = 1.41, collide: str = None)", "AStarPath | None"), + MCRF_SIG("(start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0)", "AStarPath | None"), MCRF_DESC("Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step."), MCRF_ARGS_START MCRF_ARG("start", "Starting position as Vector, Entity, or (x, y) tuple") MCRF_ARG("end", "Target position as Vector, Entity, or (x, y) tuple") MCRF_ARG("diagonal_cost", "Cost of diagonal movement (default: 1.41)") MCRF_ARG("collide", "Label string. Entities with this label block pathfinding.") + MCRF_ARG("heuristic", "Heuristic enum member, string name, or int (EUCLIDEAN=0, MANHATTAN=1, CHEBYSHEV=2). None uses default (Euclidean).") + MCRF_ARG("weight", "Heuristic weight multiplier. Values > 1.0 trade optimality for speed (weighted A*).") MCRF_RETURNS("AStarPath object if path exists, None otherwise") )}, {"get_dijkstra_map", (PyCFunction)UIGridPathfinding::Grid_get_dijkstra_map, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Grid, get_dijkstra_map, - MCRF_SIG("(root, diagonal_cost: float = 1.41, collide: str = None)", "DijkstraMap"), + MCRF_SIG("(root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None)", "DijkstraMap"), MCRF_DESC("Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate."), MCRF_ARGS_START - MCRF_ARG("root", "Root position as Vector, Entity, or (x, y) tuple") + MCRF_ARG("root", "Root position as Vector, Entity, or (x, y) tuple. Use 'root' for single-source maps (cached by position).") MCRF_ARG("diagonal_cost", "Cost of diagonal movement (default: 1.41)") MCRF_ARG("collide", "Label string. Entities with this label block pathfinding.") + MCRF_ARG("roots", "Sequence of root positions or a DiscreteMap mask for multi-source Dijkstra. Pass 'roots' instead of 'root' for multi-source maps (not cached).") MCRF_RETURNS("DijkstraMap object for querying distances and paths") )}, {"clear_dijkstra_maps", (PyCFunction)UIGridPathfinding::Grid_clear_dijkstra_maps, METH_NOARGS, @@ -1024,44 +1031,51 @@ PyMethodDef UIGrid_all_methods[] = { MCRF_ARG("y", "Row index (0-based)") MCRF_RETURNS("GridPoint: the cell at the given position") MCRF_RAISES("IndexError", "If x or y is out of range") + MCRF_NOTE("Also accepts a single positional tuple/list/Vector: at((x, y)) or at(vec), or keyword form: at(pos=(x, y)).") )}, {"compute_fov", (PyCFunction)UIGrid::py_compute_fov, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Grid, compute_fov, - MCRF_SIG("(pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC)", "None"), + MCRF_SIG("(pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC)", "None"), MCRF_DESC("Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility."), MCRF_ARGS_START MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector") MCRF_ARG("radius", "Maximum view distance (0 = unlimited)") MCRF_ARG("light_walls", "Whether walls are lit when visible") - MCRF_ARG("algorithm", "FOV algorithm to use (FOV_BASIC, FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8)") + MCRF_ARG("algorithm", "FOV algorithm to use (FOV.BASIC, FOV.DIAMOND, FOV.SHADOW, FOV.PERMISSIVE_0-8)") + MCRF_RETURNS("None") )}, {"is_in_fov", (PyCFunction)UIGrid::py_is_in_fov, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Grid, is_in_fov, - MCRF_SIG("(pos)", "bool"), + MCRF_SIG("(x: int, y: int)", "bool"), MCRF_DESC("Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility."), MCRF_ARGS_START - MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector") + MCRF_ARG("x", "Column index (0-based)") + MCRF_ARG("y", "Row index (0-based)") MCRF_RETURNS("True if the cell is visible, False otherwise") + MCRF_NOTE("Also accepts a single positional tuple/list/Vector: is_in_fov((x, y)) or is_in_fov(vec), or keyword form: is_in_fov(pos=(x, y)).") )}, {"find_path", (PyCFunction)UIGridPathfinding::Grid_find_path, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Grid, find_path, - MCRF_SIG("(start, end, diagonal_cost: float = 1.41, collide: str = None)", "AStarPath | None"), + MCRF_SIG("(start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0)", "AStarPath | None"), MCRF_DESC("Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step."), MCRF_ARGS_START MCRF_ARG("start", "Starting position as Vector, Entity, or (x, y) tuple") MCRF_ARG("end", "Target position as Vector, Entity, or (x, y) tuple") MCRF_ARG("diagonal_cost", "Cost of diagonal movement (default: 1.41)") MCRF_ARG("collide", "Label string. Entities with this label block pathfinding.") + MCRF_ARG("heuristic", "Heuristic enum member, string name, or int (EUCLIDEAN=0, MANHATTAN=1, CHEBYSHEV=2). None uses default (Euclidean).") + MCRF_ARG("weight", "Heuristic weight multiplier. Values > 1.0 trade optimality for speed (weighted A*).") MCRF_RETURNS("AStarPath object if path exists, None otherwise") )}, {"get_dijkstra_map", (PyCFunction)UIGridPathfinding::Grid_get_dijkstra_map, METH_VARARGS | METH_KEYWORDS, MCRF_METHOD(Grid, get_dijkstra_map, - MCRF_SIG("(root, diagonal_cost: float = 1.41, collide: str = None)", "DijkstraMap"), + MCRF_SIG("(root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None)", "DijkstraMap"), MCRF_DESC("Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate."), MCRF_ARGS_START - MCRF_ARG("root", "Root position as Vector, Entity, or (x, y) tuple") + MCRF_ARG("root", "Root position as Vector, Entity, or (x, y) tuple. Use 'root' for single-source maps (cached by position).") MCRF_ARG("diagonal_cost", "Cost of diagonal movement (default: 1.41)") MCRF_ARG("collide", "Label string. Entities with this label block pathfinding.") + MCRF_ARG("roots", "Sequence of root positions or a DiscreteMap mask for multi-source Dijkstra. Pass 'roots' instead of 'root' for multi-source maps (not cached).") MCRF_RETURNS("DijkstraMap object for querying distances and paths") )}, {"clear_dijkstra_maps", (PyCFunction)UIGridPathfinding::Grid_clear_dijkstra_maps, METH_NOARGS, diff --git a/src/UIGridPyProperties.cpp b/src/UIGridPyProperties.cpp index fdf208a..d480504 100644 --- a/src/UIGridPyProperties.cpp +++ b/src/UIGridPyProperties.cpp @@ -571,7 +571,7 @@ PyGetSetDef UIGrid::getsetters[] = { {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, MCRF_PROPERTY(on_click, "Callable executed when object is clicked. " - "Function receives (pos: Vector, button: str, action: str)." + "Function receives (pos: Vector, button: MouseButton, action: InputState)." ), (void*)PyObjectsEnum::UIGRID}, {"texture", (getter)UIGrid::get_texture, NULL, diff --git a/src/UIGridView.cpp b/src/UIGridView.cpp index dabfe97..a275c6e 100644 --- a/src/UIGridView.cpp +++ b/src/UIGridView.cpp @@ -888,13 +888,13 @@ PyGetSetDef UIGridView::getsetters[] = { {"grid_data", (getter)UIGridView::get_grid, (setter)UIGridView::set_grid, MCRF_PROPERTY(grid_data, "The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid."), NULL}, {"center", (getter)UIGridView::get_center, (setter)UIGridView::set_center, - MCRF_PROPERTY(center, "Camera center point in pixel coordinates (tuple)."), NULL}, + MCRF_PROPERTY(center, "Camera center point in pixel coordinates (Vector)."), NULL}, {"zoom", (getter)UIGridView::get_zoom, (setter)UIGridView::set_zoom, MCRF_PROPERTY(zoom, "Zoom level for rendering (float). Values greater than 1.0 magnify; less than 1.0 shrink."), NULL}, {"fill_color", (getter)UIGridView::get_fill_color, (setter)UIGridView::set_fill_color, MCRF_PROPERTY(fill_color, "Background fill color (Color). Drawn behind all tiles and entities."), NULL}, {"texture", (getter)UIGridView::get_texture, NULL, - MCRF_PROPERTY(texture, "Texture used for tile rendering (Texture | None, read-only)."), NULL}, + MCRF_PROPERTY(texture, "Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None."), NULL}, // UIDrawable base properties - applied to GridView (the rendered object) {"pos", (getter)UIDrawable::get_pos, (setter)UIDrawable::set_pos, MCRF_PROPERTY(pos, "Position of the grid as Vector (Vector)."), (void*)PyObjectsEnum::UIGRIDVIEW}, diff --git a/src/UILine.cpp b/src/UILine.cpp index 0feb4c8..85d4307 100644 --- a/src/UILine.cpp +++ b/src/UILine.cpp @@ -517,7 +517,7 @@ PyGetSetDef UILine::getsetters[] = { {"thickness", (getter)UILine::get_thickness, (setter)UILine::set_thickness, MCRF_PROPERTY(thickness, "Line thickness in pixels."), NULL}, {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, - MCRF_PROPERTY(on_click, "Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str)."), + MCRF_PROPERTY(on_click, "Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState)."), (void*)PyObjectsEnum::UILINE}, {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, MCRF_PROPERTY(z_index, "Z-order for rendering (lower values rendered first)."), diff --git a/src/UISprite.cpp b/src/UISprite.cpp index 5a69a34..5211b89 100644 --- a/src/UISprite.cpp +++ b/src/UISprite.cpp @@ -441,7 +441,7 @@ PyGetSetDef UISprite::getsetters[] = { {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, MCRF_PROPERTY(on_click, "Callable executed when object is clicked. " - "Function receives (pos: Vector, button: str, action: str)." + "Function receives (pos: Vector, button: MouseButton, action: InputState)." ), (void*)PyObjectsEnum::UISPRITE}, {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, MCRF_PROPERTY(z_index, diff --git a/stubs/mcrfpy.pyi b/stubs/mcrfpy.pyi index a37e2a4..12482a9 100644 --- a/stubs/mcrfpy.pyi +++ b/stubs/mcrfpy.pyi @@ -267,11 +267,11 @@ class Arc: """An arc UI element for drawing curved line segments.""" def __init__(self, center=None, radius=0, start_angle=0, end_angle=90, color=None, thickness=1, **kwargs) -> None: ... align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ... - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). center: Vector # Center position of the arc (Vector). color: Color # Arc fill color (Color). end_angle: float # Ending angle in degrees (float). - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_pos: Vector # Position in grid tile coordinates (Vector, only when parent is Grid). grid_size: Vector # Size in grid tile coordinates (Vector, only when parent is Grid). @@ -279,10 +279,10 @@ class Arc: hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr... name: str # Name for finding this element (str). - on_click: Any # Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_click: Any # Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. origin: Any # 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: Any # 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. @@ -338,7 +338,7 @@ class BSP: def clear(self) -> BSP: """Remove all children, keeping only the root node with original bounds. WARNING: Invalidates all existing BSPNode references from this tree.""" ... - def find(self, pos: tuple[int, int]) -> BSPNode | None: + def find(self, pos: tuple[int, int] | list | Vector) -> BSPNode | None: """Find the smallest (deepest) node containing the position.""" ... def get_leaf(self, index: int) -> BSPNode: @@ -350,10 +350,10 @@ class BSP: def split_once(self, horizontal: bool, position: int) -> BSP: """Split the root node once at the specified position. horizontal=True creates a horizontal divider, producing top/bottom rooms. horizontal=False creates a vert...""" ... - def split_recursive(self, depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP: + def split_recursive(self, depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP: """Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree.""" ... - def to_heightmap(self, size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap: + def to_heightmap(self, size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap: """Convert BSP node selection to a HeightMap.""" ... def traverse(self, order: Traversal = Traversal.LEVEL_ORDER) -> Iterator[BSPNode]: @@ -384,10 +384,10 @@ class Caption: """A text display UI element with customizable font and styling.""" def __init__(self, pos=None, font=None, text='', **kwargs) -> None: ... align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ... - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). fill_color: Color # Fill color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc. font_size: int # Font size in points (int). Clamped to the range [0, 65535]. - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_pos: Vector # Position in grid tile coordinates (Vector). Only valid when parent is a Grid. grid_size: Vector # Size in grid tile coordinates (Vector). Only valid when parent is a Grid. @@ -396,10 +396,10 @@ class Caption: hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr... name: str # Name for finding elements (str). - on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. origin: Any # 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: float # Thickness of the text outline border (float). Clamped to non-negative values. @@ -435,10 +435,10 @@ class Circle: """A circle UI element for drawing filled or outlined circles.""" def __init__(self, radius=0, center=None, fill_color=None, outline_color=None, outline=0, **kwargs) -> None: ... align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ... - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). center: Vector # Center position of the circle (Vector). fill_color: Color # Fill color of the circle (Color). - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_pos: Vector # Position in grid tile coordinates (Vector). Only meaningful when parent is a Grid. grid_size: Vector # Size in grid tile coordinates (Vector). Only meaningful when parent is a Grid. @@ -446,10 +446,10 @@ class Circle: hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr... name: str # Name for finding this element (str). - on_click: Callable | None # Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: str, action: str). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_click: Callable | None # Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState). + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. origin: Any # 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: float # Outline thickness in pixels (float). Use 0 for no outline. @@ -503,7 +503,7 @@ class ColorLayer: def apply_gradient(self, source: HeightMap, range: tuple, color_low: Color, color_high: Color) -> ColorLayer: """Interpolate between two colors based on HeightMap value within a range. Uses the original heightmap value for smooth transitions.""" ... - def apply_perspective(self, entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None: + def apply_perspective(self, entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None: """Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves.""" ... def apply_ranges(self, source: HeightMap, ranges: list) -> ColorLayer: @@ -513,12 +513,12 @@ class ColorLayer: """Set a fixed color for cells where the HeightMap value falls within a range.""" ... def at(self, *args, **kwargs) -> Any: - """at(pos) or (x: int, y: int) -> Color""" + """at(pos: tuple | Vector) or (x: int, y: int) -> Color""" ... def clear_perspective(self) -> None: """Remove the perspective binding from this layer.""" ... - def draw_fov(self, source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None: + def draw_fov(self, source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None: """Paint cells based on field-of-view visibility from a source position.""" ... def fill(self, color: Color) -> None: @@ -638,7 +638,7 @@ class DiscreteMap: class Drawable: """Base class for all drawable UI elements""" def __init__(self, *args, **kwargs) -> None: ... - on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). + on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable. z_index: Any # Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed. @@ -725,7 +725,7 @@ class Entity: def update_visibility(self) -> None: """Recompute which cells are visible from this entity's position and update perspective_map.""" ... - def visible_entities(self, fov=None, radius: int = None) -> list[Entity]: + def visible_entities(self, fov=None, radius: int = -1) -> list[Entity]: """Get list of other entities visible from this entity's position.""" ... @@ -811,12 +811,12 @@ class Frame: """A rectangular frame UI element that can contain other drawable elements.""" def __init__(self, pos=None, size=None, **kwargs) -> None: ... align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ... - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). cache_subtree: bool # Cache the frame and all children to a render texture for performance (bool). Useful for complex static subtrees. children: UICollection # UICollection of child drawable objects rendered on top of this frame (UICollection, read-only). clip_children: bool # Whether to clip child elements to the frame's bounds (bool). Enables render-texture mode when True. fill_color: Color # Fill color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc. - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_pos: Vector # Position in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid. grid_size: Vector # Size in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid. @@ -825,10 +825,10 @@ class Frame: hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr... name: str # Name for finding elements (str). - on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. origin: Any # 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: float # Thickness of the border in pixels (float). @@ -862,9 +862,9 @@ class Grid: """A grid-based UI element for tile-based rendering and entity management.""" def __init__(self, grid_size=None, pos=None, size=None, texture=None, **kwargs) -> None: ... align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ... - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). camera_rotation: float # Rotation of grid contents around camera center in degrees (float). - center: tuple # Camera center point in pixel coordinates (tuple). + center: Vector # Camera center point in pixel coordinates (Vector). center_x: float # Camera center X-coordinate in pixel space (float). center_y: float # Camera center Y-coordinate in pixel space (float). children: UICollection # UICollection of UIDrawable children such as speech bubbles, effects, and overlays (UICollection, read-only). @@ -872,7 +872,7 @@ class Grid: fill_color: Color # Background fill color (Color). Drawn behind all tiles and entities. fov: Any # FOV algorithm for this grid (FOV enum). Used by entity.updateVisibility() and layer methods when fov=None. fov_radius: int # Default FOV radius for this grid (int). Used when radius is not specified. - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_data: Grid | None # The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid. grid_h: int # Grid height in cells (int, read-only). @@ -890,9 +890,9 @@ class Grid: on_cell_enter: Callable | None # Callback when mouse enters a grid cell (Callable | None). Called with (cell_pos: Vector). on_cell_exit: Callable | None # Callback when mouse exits a grid cell (Callable | None). Called with (cell_pos: Vector). on_click: Callable | None # Callable executed when object is clicked (Callable | None). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. origin: Any # 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: Any # 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. @@ -903,7 +903,7 @@ class Grid: rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property. shader: Any # 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: Vector # Size of the grid widget as Vector (Vector, width x height in pixels). - texture: Texture | None # Texture used for tile rendering (Texture | None, read-only). + texture: None # Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None. uniforms: Any # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/... vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER). view: GridView | None # Auto-created GridView for rendering (GridView | None, read-only). When Grid is appended to a scene, this view is what actually renders. @@ -934,19 +934,19 @@ class Grid: def clear_dijkstra_maps(self) -> None: """Clear all cached Dijkstra maps. Call this after modifying grid cell walkability to ensure pathfinding uses updated walkability data.""" ... - def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None: + def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC) -> None: """Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility.""" ... def entities_in_radius(self, pos: tuple | Vector, radius: float) -> list: """Query entities within radius using spatial hash (O(k) where k = nearby entities).""" ... - def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None) -> AStarPath | None: + def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0) -> AStarPath | None: """Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step.""" ... - def get_dijkstra_map(self, root, diagonal_cost: float = 1.41, collide: str = None) -> DijkstraMap: + def get_dijkstra_map(self, root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None) -> DijkstraMap: """Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate.""" ... - def is_in_fov(self, pos) -> bool: + def is_in_fov(self, x: int, y: int) -> bool: """Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility.""" ... def layer(self, name: str) -> ColorLayer | TileLayer | None: @@ -972,9 +972,9 @@ class GridView: """A grid-based UI element for tile-based rendering and entity management.""" def __init__(self, *args, **kwargs) -> None: ... align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ... - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). camera_rotation: float # Rotation of grid contents around camera center in degrees (float). - center: tuple # Camera center point in pixel coordinates (tuple). + center: Vector # Camera center point in pixel coordinates (Vector). center_x: float # Camera center X-coordinate in pixel space (float). center_y: float # Camera center Y-coordinate in pixel space (float). children: UICollection # UICollection of UIDrawable children such as speech bubbles, effects, and overlays (UICollection, read-only). @@ -982,7 +982,7 @@ class GridView: fill_color: Color # Background fill color (Color). Drawn behind all tiles and entities. fov: Any # FOV algorithm for this grid (FOV enum). Used by entity.updateVisibility() and layer methods when fov=None. fov_radius: int # Default FOV radius for this grid (int). Used when radius is not specified. - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_data: Grid | None # The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid. grid_h: int # Grid height in cells (int, read-only). @@ -1000,9 +1000,9 @@ class GridView: on_cell_enter: Callable | None # Callback when mouse enters a grid cell (Callable | None). Called with (cell_pos: Vector). on_cell_exit: Callable | None # Callback when mouse exits a grid cell (Callable | None). Called with (cell_pos: Vector). on_click: Callable | None # Callable executed when object is clicked (Callable | None). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. origin: Any # 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: Any # 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. @@ -1013,7 +1013,7 @@ class GridView: rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property. shader: Any # 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: Vector # Size of the grid widget as Vector (Vector, width x height in pixels). - texture: Texture | None # Texture used for tile rendering (Texture | None, read-only). + texture: None # Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None. uniforms: Any # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/... vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER). view: GridView | None # Auto-created GridView for rendering (GridView | None, read-only). When Grid is appended to a scene, this view is what actually renders. @@ -1044,19 +1044,19 @@ class GridView: def clear_dijkstra_maps(self) -> None: """Clear all cached Dijkstra maps. Call this after modifying grid cell walkability to ensure pathfinding uses updated walkability data.""" ... - def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None: + def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC) -> None: """Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility.""" ... def entities_in_radius(self, pos: tuple | Vector, radius: float) -> list: """Query entities within radius using spatial hash (O(k) where k = nearby entities).""" ... - def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None) -> AStarPath | None: + def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0) -> AStarPath | None: """Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step.""" ... - def get_dijkstra_map(self, root, diagonal_cost: float = 1.41, collide: str = None) -> DijkstraMap: + def get_dijkstra_map(self, root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None) -> DijkstraMap: """Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate.""" ... - def is_in_fov(self, pos) -> bool: + def is_in_fov(self, x: int, y: int) -> bool: """Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility.""" ... def layer(self, name: str) -> ColorLayer | TileLayer | None: @@ -1218,10 +1218,10 @@ class Line: """A line UI element for drawing straight lines between two points.""" def __init__(self, start=None, end=None, thickness=1.0, color=None, **kwargs) -> None: ... align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ... - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). color: Any # Line color as a Color object. end: Any # Ending point of the line as a Vector. - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_pos: Vector # Position in grid tile coordinates (Vector, only when parent is Grid). grid_size: Vector # Size in grid tile coordinates (Vector, only when parent is Grid). @@ -1229,10 +1229,10 @@ class Line: hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr... name: Any # Name for finding this element. - on_click: Any # Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_click: Any # Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. origin: Any # 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: Any # 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. @@ -1459,8 +1459,8 @@ class Sprite: """A sprite UI element that displays a texture or portion of a texture atlas.""" def __init__(self, pos=None, texture=None, sprite_index=0, **kwargs) -> None: ... align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ... - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_pos: Vector # Position in grid tile coordinates (Vector, only when parent is Grid). grid_size: Vector # Size in grid tile coordinates (Vector, only when parent is Grid). @@ -1468,10 +1468,10 @@ class Sprite: hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr... name: str # Name for finding elements (str). - on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. origin: Any # 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: Any # 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. @@ -1542,7 +1542,7 @@ class TileLayer: """Set a tile index for cells where the HeightMap value falls within a range.""" ... def at(self, *args, **kwargs) -> Any: - """at(pos) or (x: int, y: int) -> int""" + """at(pos: tuple | Vector) or (x: int, y: int) -> int""" ... def fill(self, index: int) -> None: """Fill the entire layer with the specified tile index.""" @@ -1667,7 +1667,7 @@ class Viewport3D: """A 3D rendering viewport that displays a 3D scene as a UI element.""" def __init__(self, pos=None, size=None, **kwargs) -> None: ... bg_color: Any # Background clear color. - bounds: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)). + bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). camera_pos: Any # Camera position as (x, y, z) tuple. camera_target: Any # Camera look-at target as (x, y, z) tuple. cell_size: Any # World units per navigation grid cell. @@ -1680,15 +1680,15 @@ class Viewport3D: fog_far: Any # Fog end distance. fog_near: Any # Fog start distance. fov: Any # Camera field of view in degrees. - global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)). + global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)). global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain. grid_size: Any # Navigation grid dimensions as (width, depth) tuple. h: Any # Display height in pixels. hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement. - on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str). - on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds. - on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds. - on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called... + on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState). + on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds. + on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds. + on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen... opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0]. parent: Any # 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: Any # Position as Vector (x, y). @@ -1980,8 +1980,8 @@ class _automation_module: """Move the mouse cursor to the specified position.""" ... @staticmethod - def onScreen(pos: tuple | list | Vector) -> bool: - """Check if a position is within the screen bounds.""" + def onScreen(self, *args, **kwargs) -> Any: + """onScreen(x: int, y: int) or (pos: tuple | list | Vector) -> bool""" ... @staticmethod def position() -> Vector: @@ -2014,7 +2014,7 @@ class _automation_module: automation: _automation_module # --- Module-level functions --------------------------------------------- -def bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]: +def bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]: """Compute grid cells along a line using Bresenham's algorithm.""" ... def end_benchmark() -> str: diff --git a/tests/snapshots/api_surface.golden.txt b/tests/snapshots/api_surface.golden.txt index f049d2f..4646f25 100644 --- a/tests/snapshots/api_surface.golden.txt +++ b/tests/snapshots/api_surface.golden.txt @@ -3,7 +3,7 @@ # Singleton/constant VALUES are intentionally NOT captured. === MODULE FUNCTIONS (12) === -func bresenham :: bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]] +func bresenham :: bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]] func end_benchmark :: end_benchmark() -> str func exit :: exit() -> None func find :: find(name: str, scene: str = None) -> UIDrawable | None @@ -253,11 +253,11 @@ submodule automation meth walk :: walk() -> Vector [Arc] prop align: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop center: Vector (rw) prop color: Color (rw) prop end_angle: float (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_pos: Vector (rw) prop grid_size: Vector (rw) @@ -292,19 +292,19 @@ submodule automation prop root: Any (ro) prop size: Any (ro) meth clear :: clear() -> BSP - meth find :: find(pos: tuple[int, int]) -> BSPNode | None + meth find :: find(pos: tuple[int, int] | list | Vector) -> BSPNode | None meth get_leaf :: get_leaf(index: int) -> BSPNode meth leaves :: leaves() -> Iterator[BSPNode] meth split_once :: split_once(horizontal: bool, position: int) -> BSP - meth split_recursive :: split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP - meth to_heightmap :: to_heightmap(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap + meth split_recursive :: split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP + meth to_heightmap :: to_heightmap(size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap meth traverse :: traverse(order: Traversal = Traversal.LEVEL_ORDER) -> Iterator[BSPNode] [Caption] prop align: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop fill_color: Color (rw) prop font_size: int (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_pos: Vector (rw) prop grid_size: Vector (rw) @@ -341,10 +341,10 @@ submodule automation meth resize :: resize(width, height) or (size) -> None [Circle] prop align: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop center: Vector (rw) prop fill_color: Color (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_pos: Vector (rw) prop grid_size: Vector (rw) @@ -387,12 +387,12 @@ submodule automation prop visible: bool (rw) prop z_index: int (rw) meth apply_gradient :: apply_gradient(source: HeightMap, range: tuple, color_low: Color, color_high: Color) -> ColorLayer - meth apply_perspective :: apply_perspective(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None + meth apply_perspective :: apply_perspective(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None meth apply_ranges :: apply_ranges(source: HeightMap, ranges: list) -> ColorLayer meth apply_threshold :: apply_threshold(source: HeightMap, range: tuple, color: Color) -> ColorLayer - meth at :: at(pos) or (x: int, y: int) -> Color + meth at :: at(pos: tuple | Vector) or (x: int, y: int) -> Color meth clear_perspective :: clear_perspective() -> None - meth draw_fov :: draw_fov(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None + meth draw_fov :: draw_fov(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None meth fill :: fill(color: Color) -> None meth fill_rect :: fill_rect(pos: tuple, size: tuple, color: Color) -> None meth set :: set(pos, color: Color) -> None @@ -487,18 +487,18 @@ submodule automation meth resize :: resize(width, height) or (size) -> None meth set_behavior :: set_behavior(type, waypoints=None, turns: int = 0, path=None, pathfinder=None) -> None meth update_visibility :: update_visibility() -> None - meth visible_entities :: visible_entities(fov=None, radius: int = None) -> list[Entity] + meth visible_entities :: visible_entities(fov=None, radius: int = -1) -> list[Entity] [Font] prop family: str (ro) prop source: str (ro) [Frame] prop align: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop cache_subtree: bool (rw) prop children: UICollection (ro) prop clip_children: bool (rw) prop fill_color: Color (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_pos: Vector (rw) prop grid_size: Vector (rw) @@ -533,13 +533,13 @@ submodule automation meth resize :: resize(width, height) or (size) -> None [Grid] prop align: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop camera_rotation: float (rw) - prop center: tuple (rw) + prop center: Vector (rw) prop center_x: float (rw) prop center_y: float (rw) prop fill_color: Color (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_data: Grid | None (rw) prop h: float (rw) @@ -558,7 +558,7 @@ submodule automation prop rotate_with_camera: bool (rw) prop rotation: Any (rw) prop shader: Any (rw) - prop texture: Texture | None (ro) + prop texture: None (ro) prop uniforms: Any (ro) prop vert_margin: float (rw) prop visible: bool (rw) @@ -573,13 +573,13 @@ submodule automation meth resize :: resize(width, height) or (size) -> None [GridView] prop align: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop camera_rotation: float (rw) - prop center: tuple (rw) + prop center: Vector (rw) prop center_x: float (rw) prop center_y: float (rw) prop fill_color: Color (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_data: Grid | None (rw) prop h: float (rw) @@ -598,7 +598,7 @@ submodule automation prop rotate_with_camera: bool (rw) prop rotation: Any (rw) prop shader: Any (rw) - prop texture: Texture | None (ro) + prop texture: None (ro) prop uniforms: Any (ro) prop vert_margin: float (rw) prop visible: bool (rw) @@ -655,10 +655,10 @@ submodule automation prop system: Any (ro) [Line] prop align: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop color: Any (rw) prop end: Any (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_pos: Vector (rw) prop grid_size: Vector (rw) @@ -764,8 +764,8 @@ submodule automation meth tone :: tone(frequency: float, duration: float, waveform: str = 'sine', ...) -> SoundBuffer [Sprite] prop align: Any (rw) - prop bounds: Any (rw) - prop global_bounds: Any (rw) + prop bounds: tuple (ro) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_pos: Vector (rw) prop grid_size: Vector (rw) @@ -822,7 +822,7 @@ submodule automation prop z_index: int (rw) meth apply_ranges :: apply_ranges(source: HeightMap, ranges: list) -> TileLayer meth apply_threshold :: apply_threshold(source: HeightMap, range: tuple, tile: int) -> TileLayer - meth at :: at(pos) or (x: int, y: int) -> int + meth at :: at(pos: tuple | Vector) or (x: int, y: int) -> int meth fill :: fill(index: int) -> None meth fill_rect :: fill_rect(pos: tuple, size: tuple, index: int) -> None meth set :: set(pos, index: int) -> None @@ -989,7 +989,7 @@ submodule automation meth wang_set :: wang_set(name: str) -> WangSet [Viewport3D] prop bg_color: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop camera_pos: Any (rw) prop camera_target: Any (rw) prop cell_size: Any (rw) @@ -1002,7 +1002,7 @@ submodule automation prop fog_far: Any (rw) prop fog_near: Any (rw) prop fov: Any (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_size: Any (rw) prop h: Any (rw) @@ -1105,7 +1105,7 @@ submodule automation === INTERNAL TYPES (reached via live instances) === [_GridData] prop align: Any (rw) - prop bounds: Any (rw) + prop bounds: tuple (ro) prop camera_rotation: float (rw) prop center: Vector (rw) prop center_x: float (rw) @@ -1115,7 +1115,7 @@ submodule automation prop fill_color: Color (rw) prop fov: Any (rw) prop fov_radius: int (rw) - prop global_bounds: Any (rw) + prop global_bounds: tuple (ro) prop global_position: Any (ro) prop grid_h: int (ro) prop grid_pos: Vector (rw) @@ -1162,11 +1162,11 @@ submodule automation meth at :: at(x: int, y: int) -> GridPoint meth center_camera :: center_camera(pos: tuple = None) -> None meth clear_dijkstra_maps :: clear_dijkstra_maps() -> None - meth compute_fov :: compute_fov(pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None + meth compute_fov :: compute_fov(pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC) -> None meth entities_in_radius :: entities_in_radius(pos: tuple | Vector, radius: float) -> list - meth find_path :: find_path(start, end, diagonal_cost: float = 1.41, collide: str = None) -> AStarPath | None - meth get_dijkstra_map :: get_dijkstra_map(root, diagonal_cost: float = 1.41, collide: str = None) -> DijkstraMap - meth is_in_fov :: is_in_fov(pos) -> bool + meth find_path :: find_path(start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0) -> AStarPath | None + meth get_dijkstra_map :: get_dijkstra_map(root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None) -> DijkstraMap + meth is_in_fov :: is_in_fov(x: int, y: int) -> bool meth layer :: layer(name: str) -> ColorLayer | TileLayer | None meth move :: move(dx, dy) or (delta) -> None meth realign :: realign() -> None @@ -1175,14 +1175,14 @@ submodule automation meth step :: step(n: int = 1, turn_order: int = None) -> None [GridPoint] prop entities: list (ro) - prop grid_pos: Any (ro) + prop grid_pos: tuple (ro) prop transparent: bool (rw) prop walkable: bool (rw) [EntityCollection] meth append :: append(entity: Entity) -> None meth count :: count(entity: Entity) -> int meth extend :: extend(iterable) -> None - meth find :: find(name: str) -> Entity | list | None + meth find :: find(name: str) -> Entity | list[Entity] | None meth index :: index(entity: Entity) -> int meth insert :: insert(index: int, entity: Entity) -> None meth pop :: pop(index: int = -1) -> Entity @@ -1190,7 +1190,7 @@ submodule automation [UICollection] meth append :: append(element: Drawable) -> None meth count :: count(element: Drawable) -> int - meth extend :: extend(iterable) -> None + meth extend :: extend(iterable: Iterable[Drawable]) -> None meth find :: find(name: str, recursive: bool = False) -> Drawable | list | None meth index :: index(element: Drawable) -> int meth insert :: insert(index: int, element: Drawable) -> None @@ -1215,7 +1215,7 @@ func mouseDown :: mouseDown(pos: tuple | list | Vector | None = None, button: st func mouseUp :: mouseUp(pos: tuple | list | Vector | None = None, button: str = 'left') -> None func moveRel :: moveRel(offset: tuple | list | Vector, duration: float = 0.0) -> None func moveTo :: moveTo(pos: tuple | list | Vector, duration: float = 0.0) -> None -func onScreen :: onScreen(pos: tuple | list | Vector) -> bool +func onScreen :: onScreen(x: int, y: int) or (pos: tuple | list | Vector) -> bool func position :: position() -> Vector func rightClick :: rightClick(pos: tuple | list | Vector | None = None) -> None func screenshot :: screenshot(filename: str) -> bool