diff --git a/docs/API_REFERENCE_DYNAMIC.md b/docs/API_REFERENCE_DYNAMIC.md new file mode 100644 index 0000000..4cf6ae8 --- /dev/null +++ b/docs/API_REFERENCE_DYNAMIC.md @@ -0,0 +1,1607 @@ +# McRogueFace API Reference + +*Generated on 2025-12-28 14:29:42* + +*This documentation was dynamically generated from the compiled module.* + +## Table of Contents + +- [Functions](#functions) +- [Classes](#classes) + - [Animation](#animation) + - [Arc](#arc) + - [Caption](#caption) + - [Circle](#circle) + - [Color](#color) + - [ColorLayer](#colorlayer) + - [Drawable](#drawable) + - [Entity](#entity) + - [EntityCollection](#entitycollection) + - [FOV](#fov) + - [Font](#font) + - [Frame](#frame) + - [Grid](#grid) + - [GridPoint](#gridpoint) + - [GridPointState](#gridpointstate) + - [Line](#line) + - [Scene](#scene) + - [Sprite](#sprite) + - [Texture](#texture) + - [TileLayer](#tilelayer) + - [Timer](#timer) + - [UICollection](#uicollection) + - [UICollectionIter](#uicollectioniter) + - [UIEntityCollectionIter](#uientitycollectioniter) + - [Vector](#vector) + - [Window](#window) +- [Constants](#constants) + +## Functions + +### `createScene(name: str) -> None` + +Create a new empty scene. + +Note: + +**Arguments:** +- `name`: Unique name for the new scene + +**Returns:** None + +**Raises:** ValueError: If a scene with this name already exists The scene is created but not made active. Use setScene() to switch to it. + +### `createSoundBuffer(filename: str) -> int` + +Load a sound effect from a file and return its buffer ID. + +**Arguments:** +- `filename`: Path to the sound file (WAV, OGG, FLAC) + +**Returns:** int: Buffer ID for use with playSound() + +**Raises:** RuntimeError: If the file cannot be loaded + +### `currentScene() -> str` + +Get the name of the currently active scene. + +**Returns:** str: Name of the current scene + +### `delTimer(name: str) -> None` + +Stop and remove a timer. + +Note: + +**Arguments:** +- `name`: Timer identifier to remove + +**Returns:** None No error is raised if the timer doesn't exist. + +### `end_benchmark() -> str` + +Stop benchmark capture and write data to JSON file. + +Note: + +**Returns:** str: The filename of the written benchmark data + +**Raises:** RuntimeError: If no benchmark is currently running Returns the auto-generated filename (e.g., 'benchmark_12345_20250528_143022.json') + +### `exit() -> None` + +Cleanly shut down the game engine and exit the application. + +Note: + +**Returns:** None This immediately closes the window and terminates the program. + +### `find(name: str, scene: str = None) -> UIDrawable | None` + +Find the first UI element with the specified name. + +Note: + +**Arguments:** +- `name`: Exact name to search for +- `scene`: Scene to search in (default: current scene) + +**Returns:** Frame, Caption, Sprite, Grid, or Entity if found; None otherwise Searches scene UI elements and entities within grids. + +### `findAll(pattern: str, scene: str = None) -> list` + +Find all UI elements matching a name pattern. + +Note: + +**Arguments:** +- `pattern`: Name pattern with optional wildcards (* matches any characters) +- `scene`: Scene to search in (default: current scene) + +**Returns:** list: All matching UI elements and entities + +### `getMetrics() -> 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) + +### `getMusicVolume() -> int` + +Get the current music volume level. + +**Returns:** int: Current volume (0-100) + +### `getSoundVolume() -> int` + +Get the current sound effects volume level. + +**Returns:** int: Current volume (0-100) + +### `keypressScene(handler: callable) -> None` + +Set the keyboard event handler for the current scene. + +Note: + +**Arguments:** +- `handler`: Callable that receives (key_name: str, is_pressed: bool) + +**Returns:** None + +### `loadMusic(filename: str) -> None` + +Load and immediately play background music from a file. + +Note: + +**Arguments:** +- `filename`: Path to the music file (WAV, OGG, FLAC) + +**Returns:** None Only one music track can play at a time. Loading new music stops the current track. + +### `log_benchmark(message: str) -> None` + +Add a log message to the current benchmark frame. + +Note: + +**Arguments:** +- `message`: Text to associate with the current frame + +**Returns:** None + +**Raises:** RuntimeError: If no benchmark is currently running Messages appear in the 'logs' array of each frame in the output JSON. + +### `playSound(buffer_id: int) -> None` + +Play a sound effect using a previously loaded buffer. + +**Arguments:** +- `buffer_id`: Sound buffer ID returned by createSoundBuffer() + +**Returns:** None + +**Raises:** RuntimeError: If the buffer ID is invalid + +### `sceneUI(scene: str = None) -> list` + +Get all UI elements for a scene. + +**Arguments:** +- `scene`: Scene name. If None, uses current scene + +**Returns:** list: All UI elements (Frame, Caption, Sprite, Grid) in the scene + +**Raises:** KeyError: If the specified scene doesn't exist + +### `setDevConsole(enabled: bool) -> None` + +Enable or disable the developer console overlay. + +Note: + +**Arguments:** +- `enabled`: True to enable the console (default), False to disable + +**Returns:** None When disabled, the grave/tilde key will not open the console. Use this to ship games without debug features. + +### `setMusicVolume(volume: int) -> None` + +Set the global music volume. + +**Arguments:** +- `volume`: Volume level from 0 (silent) to 100 (full volume) + +**Returns:** None + +### `setScale(multiplier: float) -> None` + +Scale the game window size. + +Note: + +**Arguments:** +- `multiplier`: Scale factor (e.g., 2.0 for double size) + +**Returns:** None The internal resolution remains 1024x768, but the window is scaled. This is deprecated - use Window.resolution instead. + +### `setScene(scene: str, transition: str = None, duration: float = 0.0) -> None` + +Switch to a different scene with optional transition effect. + +**Arguments:** +- `scene`: Name of the scene to switch to +- `transition`: Transition type ('fade', 'slide_left', 'slide_right', 'slide_up', 'slide_down') +- `duration`: Transition duration in seconds (default: 0.0 for instant) + +**Returns:** None + +**Raises:** KeyError: If the scene doesn't exist ValueError: If the transition type is invalid + +### `setSoundVolume(volume: int) -> None` + +Set the global sound effects volume. + +**Arguments:** +- `volume`: Volume level from 0 (silent) to 100 (full volume) + +**Returns:** None + +### `setTimer(name: str, handler: callable, interval: int) -> None` + +Create or update a recurring timer. + +Note: + +**Arguments:** +- `name`: Unique identifier for the timer +- `handler`: Function called with (runtime: float) parameter +- `interval`: Time between calls in milliseconds + +**Returns:** None If a timer with this name exists, it will be replaced. The handler receives the total runtime in seconds as its argument. + +### `start_benchmark() -> None` + +Start capturing benchmark data to a file. + +Note: + +**Returns:** None + +**Raises:** RuntimeError: If a benchmark is already running Benchmark filename is auto-generated from PID and timestamp. Use end_benchmark() to stop and get filename. + +### `step(dt: float = None) -> float` + +Advance simulation time (headless mode only). + +Note: + +**Arguments:** +- `dt`: Time to advance in seconds. If None, advances to the next scheduled event (timer/animation). + +**Returns:** float: Actual time advanced in seconds. Returns 0.0 in windowed mode. In windowed mode, this is a no-op and returns 0.0. Use this for deterministic simulation control in headless/testing scenarios. + +## Classes + +### Animation + +Animation object for animating UI properties + +**Methods:** + +#### `complete() -> None` + +Complete the animation immediately by jumping to the final value. + +Note: + +**Returns:** None Sets elapsed = duration and applies target value immediately. Completion callback will be called if set. + +#### `get_current_value() -> Any` + +Get the current interpolated value of the animation. + +Note: + +**Returns:** Any: Current value (type depends on property: float, int, Color tuple, Vector tuple, or str) Return type matches the target property type. For sprite_index returns int, for pos returns (x, y), for fill_color returns (r, g, b, a). + +#### `hasValidTarget() -> bool` + +Check if the animation still has a valid target. + +Note: + +**Returns:** bool: True if the target still exists, False if it was destroyed Animations automatically clean up when targets are destroyed. Use this to check if manual cleanup is needed. + +#### `start(target: UIDrawable, conflict_mode: str = 'replace') -> None` + +Start the animation on a target UI element. + +Note: + +**Arguments:** +- `target`: The UI element to animate (Frame, Caption, Sprite, Grid, or Entity) +- `conflict_mode`: How to handle conflicts if property is already animating: 'replace' (default) - complete existing animation and start new one; 'queue' - wait for existing animation to complete; 'error' - raise RuntimeError if property is busy + +**Returns:** None + +**Raises:** RuntimeError: When conflict_mode='error' and property is already animating The animation will automatically stop if the target is destroyed. + +#### `update(delta_time: float) -> bool` + +Update the animation by the given time delta. + +Note: + +**Arguments:** +- `delta_time`: Time elapsed since last update in seconds + +**Returns:** bool: True if animation is still running, False if complete Typically called by AnimationManager automatically. Manual calls only needed for custom animation control. + +### Arc + +*Inherits from: Drawable* + +Arc(center=None, radius=0, start_angle=0, end_angle=90, color=None, thickness=1, **kwargs) + +An arc UI element for drawing curved line segments. + +Args: + center (tuple, optional): Center position as (x, y). Default: (0, 0) + radius (float, optional): Arc radius in pixels. Default: 0 + start_angle (float, optional): Starting angle in degrees. Default: 0 + end_angle (float, optional): Ending angle in degrees. Default: 90 + color (Color, optional): Arc color. Default: White + thickness (float, optional): Line thickness. Default: 1.0 + +Keyword Args: + on_click (callable): Click handler. Default: None + visible (bool): Visibility state. Default: True + opacity (float): Opacity (0.0-1.0). Default: 1.0 + z_index (int): Rendering order. Default: 0 + name (str): Element name for finding. Default: None + +Attributes: + center (Vector): Center position + radius (float): Arc radius + start_angle (float): Starting angle in degrees + end_angle (float): Ending angle in degrees + color (Color): Arc color + thickness (float): Line thickness + visible (bool): Visibility state + opacity (float): Opacity value + z_index (int): Rendering order + name (str): Element name + + +**Methods:** + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +### Caption + +*Inherits from: Drawable* + +Caption(pos=None, font=None, text='', **kwargs) + +A text display UI element with customizable font and styling. + +Args: + pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) + font (Font, optional): Font object for text rendering. Default: engine default font + text (str, optional): The text content to display. Default: '' + +Keyword Args: + fill_color (Color): Text fill color. Default: (255, 255, 255, 255) + outline_color (Color): Text outline color. Default: (0, 0, 0, 255) + outline (float): Text outline thickness. Default: 0 + font_size (float): Font size in points. Default: 16 + click (callable): Click event handler. Default: None + visible (bool): Visibility state. Default: True + opacity (float): Opacity (0.0-1.0). Default: 1.0 + z_index (int): Rendering order. Default: 0 + name (str): Element name for finding. Default: None + x (float): X position override. Default: 0 + y (float): Y position override. Default: 0 + +Attributes: + text (str): The displayed text content + x, y (float): Position in pixels + pos (Vector): Position as a Vector object + font (Font): Font used for rendering + font_size (float): Font size in points + fill_color, outline_color (Color): Text appearance + outline (float): Outline thickness + click (callable): Click event handler + visible (bool): Visibility state + opacity (float): Opacity value + z_index (int): Rendering order + name (str): Element name + w, h (float): Read-only computed size based on text and font + +**Methods:** + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +### Circle + +*Inherits from: Drawable* + +Circle(radius=0, center=None, fill_color=None, outline_color=None, outline=0, **kwargs) + +A circle UI element for drawing filled or outlined circles. + +Args: + radius (float, optional): Circle radius in pixels. Default: 0 + center (tuple, optional): Center position as (x, y). Default: (0, 0) + fill_color (Color, optional): Fill color. Default: White + outline_color (Color, optional): Outline color. Default: Transparent + outline (float, optional): Outline thickness. Default: 0 (no outline) + +Keyword Args: + on_click (callable): Click handler. Default: None + visible (bool): Visibility state. Default: True + opacity (float): Opacity (0.0-1.0). Default: 1.0 + z_index (int): Rendering order. Default: 0 + name (str): Element name for finding. Default: None + +Attributes: + radius (float): Circle radius + center (Vector): Center position + fill_color (Color): Fill color + outline_color (Color): Outline color + outline (float): Outline thickness + visible (bool): Visibility state + opacity (float): Opacity value + z_index (int): Rendering order + name (str): Element name + + +**Methods:** + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +### Color + +SFML Color Object + +**Methods:** + +#### `from_hex(hex_string: str) -> Color` + +Create a Color from a hexadecimal string. + +Note: + +**Arguments:** +- `hex_string`: Hex color string (e.g., '#FF0000', 'FF0000', '#AABBCCDD' for RGBA) + +**Returns:** Color: New Color object with values from hex string + +**Raises:** ValueError: If hex string is not 6 or 8 characters (RGB or RGBA) This is a class method. Call as Color.from_hex('#FF0000') + +#### `lerp(other: Color, t: float) -> Color` + +Linearly interpolate between this color and another. + +Note: + +**Arguments:** +- `other`: The target Color to interpolate towards +- `t`: Interpolation factor (0.0 = this color, 1.0 = other color). Automatically clamped to [0.0, 1.0] + +**Returns:** Color: New Color representing the interpolated value All components (r, g, b, a) are interpolated independently + +#### `to_hex() -> str` + +Convert this Color to a hexadecimal string. + +Note: + +**Returns:** str: Hex string in format '#RRGGBB' or '#RRGGBBAA' (if alpha < 255) Alpha component is only included if not fully opaque (< 255) + +### ColorLayer + +ColorLayer(z_index=-1, grid_size=None) + +A grid layer that stores RGBA colors per cell. + +Args: + z_index (int): Render order. Negative = below entities. Default: -1 + grid_size (tuple): Dimensions as (width, height). Default: parent grid size + +Attributes: + z_index (int): Layer z-order relative to entities + visible (bool): Whether layer is rendered + grid_size (tuple): Layer dimensions (read-only) + +Methods: + at(x, y): Get color at cell position + set(x, y, color): Set color at cell position + fill(color): Fill entire layer with color + +**Methods:** + +#### `apply_perspective(entity, visible=None, discovered=None, unknown=None)` + +Bind this layer to an entity for automatic FOV updates. + +#### `at(x, y) -> Color` + +Get the color at cell position (x, y). + +#### `clear_perspective()` + +Remove the perspective binding from this layer. + +#### `draw_fov(source, radius=None, fov=None, visible=None, discovered=None, unknown=None)` + +Paint cells based on field-of-view visibility from source position. + +Note: Layer must be attached to a grid for FOV calculation. + +#### `fill(color)` + +Fill the entire layer with the specified color. + +#### `fill_rect(pos, size, color)` + +Fill a rectangular region with a color. + +**Arguments:** +- `color`: Color object or (r, g, b[, a]) tuple + +#### `set(x, y, color)` + +Set the color at cell position (x, y). + +#### `update_perspective()` + +Redraw FOV based on the bound entity's current position. +Call this after the entity moves to update the visibility layer. + +### Drawable + +Base class for all drawable UI elements + +**Methods:** + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +### Entity + +Entity(grid_pos=None, texture=None, sprite_index=0, **kwargs) + +A game entity that exists on a grid with sprite rendering. + +Args: + grid_pos (tuple, optional): Grid position as (x, y) tuple. Default: (0, 0) + texture (Texture, optional): Texture object for sprite. Default: default texture + sprite_index (int, optional): Index into texture atlas. Default: 0 + +Keyword Args: + grid (Grid): Grid to attach entity to. Default: None + visible (bool): Visibility state. Default: True + opacity (float): Opacity (0.0-1.0). Default: 1.0 + name (str): Element name for finding. Default: None + x (float): X grid position override. Default: 0 + y (float): Y grid position override. Default: 0 + +Attributes: + pos (tuple): Grid position as (x, y) tuple + x, y (float): Grid position coordinates + draw_pos (tuple): Pixel position for rendering + gridstate (GridPointState): Visibility state for grid points + sprite_index (int): Current sprite index + visible (bool): Visibility state + opacity (float): Opacity value + name (str): Element name + +**Methods:** + +#### `at(...)` + +#### `die(...)` + +Remove this entity from its grid + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `index(...)` + +Return the index of this entity in its grid's entity collection + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `path_to(x: int, y: int) -> bool` + +Find and follow path to target position using A* pathfinding. + +**Arguments:** +- `x`: Target X coordinate +- `y`: Target Y coordinate + +**Returns:** True if a path was found and the entity started moving, False otherwise The entity will automatically move along the path over multiple frames. Call this again to change the target or repath. + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +#### `update_visibility() -> None` + +Update entity's visibility state based on current FOV. +Recomputes which cells are visible from the entity's position and updates +the entity's gridstate to track explored areas. This is called automatically +when the entity moves if it has a grid with perspective set. + +#### `visible_entities(fov=None, radius=None) -> list[Entity]` + +Get list of other entities visible from this entity's position. + +**Returns:** List of Entity objects that are within field of view. Computes FOV from this entity's position and returns all other entities whose positions fall within the visible area. + +### EntityCollection + +Iterable, indexable collection of Entities + +**Methods:** + +#### `append(entity)` + +Add an entity to the end of the collection. + +#### `count(entity) -> int` + +Count occurrences of entity in the collection. + +#### `extend(iterable)` + +Add all entities from an iterable to the collection. + +#### `find(name) -> entity or list` + +Find entities by name. + +**Returns:** Single entity if exact match, list if wildcard, None if not found. + +#### `index(entity) -> int` + +Return index of first occurrence of entity. Raises ValueError if not found. + +#### `insert(index, entity)` + +Insert entity at index. Like list.insert(), indices past the end append. + +#### `pop([index]) -> entity` + +Remove and return entity at index (default: last entity). + +#### `remove(entity)` + +Remove first occurrence of entity. Raises ValueError if not found. + +### FOV + +*Inherits from: IntEnum* + +**Methods:** + +#### `as_integer_ratio(...)` + +Return a pair of integers, whose ratio is equal to the original int. +The ratio is in lowest terms and has a positive denominator. +>>> (10).as_integer_ratio() +(10, 1) +>>> (-10).as_integer_ratio() +(-10, 1) +>>> (0).as_integer_ratio() +(0, 1) + +#### `bit_count(...)` + +Number of ones in the binary representation of the absolute value of self. +Also known as the population count. +>>> bin(13) +'0b1101' +>>> (13).bit_count() +3 + +#### `bit_length(...)` + +Number of bits necessary to represent self in binary. +>>> bin(37) +'0b100101' +>>> (37).bit_length() +6 + +#### `conjugate(...)` + +Returns self, the complex conjugate of any int. + +#### `from_bytes(...)` + +Return the integer represented by the given array of bytes. + bytes + Holds the array of bytes to convert. The argument must either + support the buffer protocol or be an iterable object producing bytes. + Bytes and bytearray are examples of built-in objects that support the + buffer protocol. + byteorder + The byte order used to represent the integer. If byteorder is 'big', + the most significant byte is at the beginning of the byte array. If + byteorder is 'little', the most significant byte is at the end of the + byte array. To request the native byte order of the host system, use + sys.byteorder as the byte order value. Default is to use 'big'. + signed + Indicates whether two's complement is used to represent the integer. + +#### `is_integer(...)` + +Returns True. Exists for duck type compatibility with float.is_integer. + +#### `to_bytes(...)` + +Return an array of bytes representing an integer. + length + Length of bytes object to use. An OverflowError is raised if the + integer is not representable with the given number of bytes. Default + is length 1. + byteorder + The byte order used to represent the integer. If byteorder is 'big', + the most significant byte is at the beginning of the byte array. If + byteorder is 'little', the most significant byte is at the end of the + byte array. To request the native byte order of the host system, use + sys.byteorder as the byte order value. Default is to use 'big'. + signed + Determines whether two's complement is used to represent the integer. + If signed is False and a negative integer is given, an OverflowError + is raised. + +### Font + +SFML Font Object + +**Methods:** + +### Frame + +*Inherits from: Drawable* + +Frame(pos=None, size=None, **kwargs) + +A rectangular frame UI element that can contain other drawable elements. + +Args: + pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) + size (tuple, optional): Size as (width, height) tuple. Default: (0, 0) + +Keyword Args: + fill_color (Color): Background fill color. Default: (0, 0, 0, 128) + outline_color (Color): Border outline color. Default: (255, 255, 255, 255) + outline (float): Border outline thickness. Default: 0 + click (callable): Click event handler. Default: None + children (list): Initial list of child drawable elements. Default: None + visible (bool): Visibility state. Default: True + opacity (float): Opacity (0.0-1.0). Default: 1.0 + z_index (int): Rendering order. Default: 0 + name (str): Element name for finding. Default: None + x (float): X position override. Default: 0 + y (float): Y position override. Default: 0 + w (float): Width override. Default: 0 + h (float): Height override. Default: 0 + clip_children (bool): Whether to clip children to frame bounds. Default: False + cache_subtree (bool): Cache rendering to texture for performance. Default: False + +Attributes: + x, y (float): Position in pixels + w, h (float): Size in pixels + pos (Vector): Position as a Vector object + fill_color, outline_color (Color): Visual appearance + outline (float): Border thickness + click (callable): Click event handler + children (list): Collection of child drawable elements + visible (bool): Visibility state + opacity (float): Opacity value + z_index (int): Rendering order + name (str): Element name + clip_children (bool): Whether to clip children to frame bounds + cache_subtree (bool): Cache subtree rendering to texture + +**Methods:** + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +### Grid + +*Inherits from: Drawable* + +Grid(pos=None, size=None, grid_size=None, texture=None, **kwargs) + +A grid-based UI element for tile-based rendering and entity management. + +Args: + pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) + size (tuple, optional): Size as (width, height) tuple. Default: auto-calculated from grid_size + grid_size (tuple, optional): Grid dimensions as (grid_x, grid_y) tuple. Default: (2, 2) + texture (Texture, optional): Texture containing tile sprites. Default: default texture + +Keyword Args: + fill_color (Color): Background fill color. Default: None + click (callable): Click event handler. Default: None + center_x (float): X coordinate of center point. Default: 0 + center_y (float): Y coordinate of center point. Default: 0 + zoom (float): Zoom level for rendering. Default: 1.0 + perspective (int): Entity perspective index (-1 for omniscient). Default: -1 + visible (bool): Visibility state. Default: True + opacity (float): Opacity (0.0-1.0). Default: 1.0 + z_index (int): Rendering order. Default: 0 + name (str): Element name for finding. Default: None + x (float): X position override. Default: 0 + y (float): Y position override. Default: 0 + w (float): Width override. Default: auto-calculated + h (float): Height override. Default: auto-calculated + grid_x (int): Grid width override. Default: 2 + grid_y (int): Grid height override. Default: 2 + +Attributes: + x, y (float): Position in pixels + w, h (float): Size in pixels + pos (Vector): Position as a Vector object + size (tuple): Size as (width, height) tuple + center (tuple): Center point as (x, y) tuple + center_x, center_y (float): Center point coordinates + zoom (float): Zoom level for rendering + grid_size (tuple): Grid dimensions (width, height) in tiles + grid_x, grid_y (int): Grid dimensions + texture (Texture): Tile texture atlas + fill_color (Color): Background color + entities (EntityCollection): Collection of entities in the grid + perspective (int): Entity perspective index + click (callable): Click event handler + visible (bool): Visibility state + opacity (float): Opacity value + z_index (int): Rendering order + name (str): Element name + +**Methods:** + +#### `add_layer(type: str, z_index: int = -1, texture: Texture = None) -> ColorLayer | TileLayer` + +Add a new layer to the grid. + +**Arguments:** +- `type`: Layer type ('color' or 'tile') +- `z_index`: Render order. Negative = below entities, >= 0 = above entities. Default: -1 +- `texture`: Texture for tile layers. Required for 'tile' type. + +**Returns:** The created ColorLayer or TileLayer object. + +#### `at(...)` + +#### `compute_astar_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]` + +Compute A* path between two points. + +**Arguments:** +- `x1`: Starting X coordinate +- `y1`: Starting Y coordinate +- `x2`: Target X coordinate +- `y2`: Target Y coordinate +- `diagonal_cost`: Cost of diagonal movement (default: 1.41) + +**Returns:** List of (x, y) tuples representing the path, empty list if no path exists Alternative A* implementation. Prefer find_path() for consistency. + +#### `compute_dijkstra(root_x: int, root_y: int, diagonal_cost: float = 1.41) -> None` + +Compute Dijkstra map from root position. + +**Arguments:** +- `root_x`: X coordinate of the root/target +- `root_y`: Y coordinate of the root/target +- `diagonal_cost`: Cost of diagonal movement (default: 1.41) + +#### `compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None` + +Compute field of view from a position. + +**Arguments:** +- `x`: X coordinate of the viewer +- `y`: Y coordinate of the viewer +- `radius`: Maximum view distance (0 = unlimited) +- `light_walls`: Whether walls are lit when visible +- `algorithm`: FOV algorithm to use (FOV_BASIC, FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8) + +#### `entities_in_radius(x: float, y: float, radius: float) -> list[Entity]` + +Query entities within radius using spatial hash (O(k) where k = nearby entities). + +**Arguments:** +- `x`: Center X coordinate +- `y`: Center Y coordinate +- `radius`: Search radius + +**Returns:** List of Entity objects within the radius. + +#### `find_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]` + +Find A* path between two points. + +**Arguments:** +- `x1`: Starting X coordinate +- `y1`: Starting Y coordinate +- `x2`: Target X coordinate +- `y2`: Target Y coordinate +- `diagonal_cost`: Cost of diagonal movement (default: 1.41) + +**Returns:** List of (x, y) tuples representing the path, empty list if no path exists Uses A* algorithm with walkability from grid cells. + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `get_dijkstra_distance(x: int, y: int) -> Optional[float]` + +Get distance from Dijkstra root to position. + +**Arguments:** +- `x`: X coordinate to query +- `y`: Y coordinate to query + +**Returns:** Distance as float, or None if position is unreachable or invalid Must call compute_dijkstra() first. + +#### `get_dijkstra_path(x: int, y: int) -> List[Tuple[int, int]]` + +Get path from position to Dijkstra root. + +**Arguments:** +- `x`: Starting X coordinate +- `y`: Starting Y coordinate + +**Returns:** List of (x, y) tuples representing path to root, empty if unreachable Must call compute_dijkstra() first. Path includes start but not root position. + +#### `is_in_fov(x: int, y: int) -> bool` + +Check if a cell is in the field of view. + +**Arguments:** +- `x`: X coordinate to check +- `y`: Y coordinate to check + +**Returns:** True if the cell is visible, False otherwise Must call compute_fov() first to calculate visibility. + +#### `layer(z_index: int) -> ColorLayer | TileLayer | None` + +Get a layer by its z_index. + +**Arguments:** +- `z_index`: The z_index of the layer to find. + +**Returns:** The layer with the specified z_index, or None if not found. + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `remove_layer(layer: ColorLayer | TileLayer) -> None` + +Remove a layer from the grid. + +**Arguments:** +- `layer`: The layer to remove. + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +### GridPoint + +UIGridPoint object + +**Methods:** + +### GridPointState + +UIGridPointState object + +**Methods:** + +### Line + +*Inherits from: Drawable* + +Line(start=None, end=None, thickness=1.0, color=None, **kwargs) + +A line UI element for drawing straight lines between two points. + +Args: + start (tuple, optional): Starting point as (x, y). Default: (0, 0) + end (tuple, optional): Ending point as (x, y). Default: (0, 0) + thickness (float, optional): Line thickness in pixels. Default: 1.0 + color (Color, optional): Line color. Default: White + +Keyword Args: + on_click (callable): Click handler. Default: None + visible (bool): Visibility state. Default: True + opacity (float): Opacity (0.0-1.0). Default: 1.0 + z_index (int): Rendering order. Default: 0 + name (str): Element name for finding. Default: None + +Attributes: + start (Vector): Starting point + end (Vector): Ending point + thickness (float): Line thickness + color (Color): Line color + visible (bool): Visibility state + opacity (float): Opacity value + z_index (int): Rendering order + name (str): Element name + + +**Methods:** + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +### Scene + +Base class for object-oriented scenes + +**Methods:** + +#### `activate() -> None` + +Make this the active scene. + +Note: + +**Returns:** None Deactivates the current scene and activates this one. Scene transitions and lifecycle callbacks are triggered. + +#### `register_keyboard(callback: callable) -> None` + +Register a keyboard event handler function. + +Note: + +**Arguments:** +- `callback`: Function that receives (key: str, pressed: bool) when keyboard events occur + +**Returns:** None Alternative to setting on_key property. Handler is called for both key press and release events. + +### Sprite + +*Inherits from: Drawable* + +Sprite(pos=None, texture=None, sprite_index=0, **kwargs) + +A sprite UI element that displays a texture or portion of a texture atlas. + +Args: + pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) + texture (Texture, optional): Texture object to display. Default: default texture + sprite_index (int, optional): Index into texture atlas. Default: 0 + +Keyword Args: + scale (float): Uniform scale factor. Default: 1.0 + scale_x (float): Horizontal scale factor. Default: 1.0 + scale_y (float): Vertical scale factor. Default: 1.0 + click (callable): Click event handler. Default: None + visible (bool): Visibility state. Default: True + opacity (float): Opacity (0.0-1.0). Default: 1.0 + z_index (int): Rendering order. Default: 0 + name (str): Element name for finding. Default: None + x (float): X position override. Default: 0 + y (float): Y position override. Default: 0 + +Attributes: + x, y (float): Position in pixels + pos (Vector): Position as a Vector object + texture (Texture): The texture being displayed + sprite_index (int): Current sprite index in texture atlas + scale (float): Uniform scale factor + scale_x, scale_y (float): Individual scale factors + click (callable): Click event handler + visible (bool): Visibility state + opacity (float): Opacity value + z_index (int): Rendering order + name (str): Element name + w, h (float): Read-only computed size based on texture and scale + +**Methods:** + +#### `get_bounds() -> tuple` + +Get the bounding rectangle of this drawable element. + +Note: + +**Returns:** tuple: (x, y, width, height) representing the element's bounds The bounds are in screen coordinates and account for current position and size. + +#### `move(dx: float, dy: float) -> None` + +Move the element by a relative offset. + +Note: + +**Arguments:** +- `dx`: Horizontal offset in pixels +- `dy`: Vertical offset in pixels + +#### `resize(width: float, height: float) -> None` + +Resize the element to new dimensions. + +Note: + +**Arguments:** +- `width`: New width in pixels +- `height`: New height in pixels + +### Texture + +SFML Texture Object + +**Methods:** + +### TileLayer + +TileLayer(z_index=-1, texture=None, grid_size=None) + +A grid layer that stores sprite indices per cell. + +Args: + z_index (int): Render order. Negative = below entities. Default: -1 + texture (Texture): Sprite atlas for tile rendering. Default: None + grid_size (tuple): Dimensions as (width, height). Default: parent grid size + +Attributes: + z_index (int): Layer z-order relative to entities + visible (bool): Whether layer is rendered + texture (Texture): Tile sprite atlas + grid_size (tuple): Layer dimensions (read-only) + +Methods: + at(x, y): Get tile index at cell position + set(x, y, index): Set tile index at cell position + fill(index): Fill entire layer with tile index + +**Methods:** + +#### `at(x, y) -> int` + +Get the tile index at cell position (x, y). Returns -1 if no tile. + +#### `fill(index)` + +Fill the entire layer with the specified tile index. + +#### `fill_rect(pos, size, index)` + +Fill a rectangular region with a tile index. + +#### `set(x, y, index)` + +Set the tile index at cell position (x, y). Use -1 for no tile. + +### Timer + +Timer(name, callback, interval, once=False) + +Create a timer that calls a function at regular intervals. + +Args: + name (str): Unique identifier for the timer + callback (callable): Function to call - receives (timer, runtime) args + interval (int): Time between calls in milliseconds + once (bool): If True, timer stops after first call. Default: False + +Attributes: + interval (int): Time between calls in milliseconds + remaining (int): Time until next call in milliseconds (read-only) + paused (bool): Whether timer is paused (read-only) + active (bool): Whether timer is active and not paused (read-only) + callback (callable): The callback function + once (bool): Whether timer stops after firing once + +Methods: + pause(): Pause the timer, preserving time remaining + resume(): Resume a paused timer + cancel(): Stop and remove the timer + restart(): Reset timer to start from beginning + +Example: + def on_timer(timer, runtime): + print(f'Timer {timer} fired at {runtime}ms') + if runtime > 5000: + timer.cancel() + + timer = mcrfpy.Timer('my_timer', on_timer, 1000) + timer.pause() # Pause timer + timer.resume() # Resume timer + timer.once = True # Make it one-shot + +**Methods:** + +#### `cancel() -> None` + +Cancel the timer and remove it from the timer system. + +Note: + +**Returns:** None The timer will no longer fire and cannot be restarted. The callback will not be called again. + +#### `pause() -> None` + +Pause the timer, preserving the time remaining until next trigger. + +Note: + +**Returns:** None The timer can be resumed later with resume(). Time spent paused does not count toward the interval. + +#### `restart() -> None` + +Restart the timer from the beginning. + +Note: + +**Returns:** None Resets the timer to fire after a full interval from now, regardless of remaining time. + +#### `resume() -> None` + +Resume a paused timer from where it left off. + +Note: + +**Returns:** None Has no effect if the timer is not paused. Timer will fire after the remaining time elapses. + +### UICollection + +Iterable, indexable collection of UI objects + +**Methods:** + +#### `append(element)` + +Add an element to the end of the collection. + +#### `count(element) -> int` + +Count occurrences of element in the collection. + +#### `extend(iterable)` + +Add all elements from an iterable to the collection. + +#### `find(name, recursive=False) -> element or list` + +Find elements by name. + +**Returns:** Single element if exact match, list if wildcard, None if not found. + +#### `index(element) -> int` + +Return index of first occurrence of element. Raises ValueError if not found. + +#### `insert(index, element)` + +Insert element at index. Like list.insert(), indices past the end append. + +Note: If using z_index for sorting, insertion order may not persist after +the next render. Use name-based .find() for stable element access. + +#### `pop([index]) -> element` + +Remove and return element at index (default: last element). + +Note: If using z_index for sorting, indices may shift after render. +Use name-based .find() for stable element access. + +#### `remove(element)` + +Remove first occurrence of element. Raises ValueError if not found. + +### UICollectionIter + +Iterator for a collection of UI objects + +**Methods:** + +### UIEntityCollectionIter + +Iterator for a collection of UI objects + +**Methods:** + +### Vector + +SFML Vector Object + +**Methods:** + +#### `angle() -> float` + +Get the angle of this vector in radians. + +**Returns:** float: Angle in radians from positive x-axis + +#### `copy() -> Vector` + +Create a copy of this vector. + +**Returns:** Vector: New Vector object with same x and y values + +#### `distance_to(other: Vector) -> float` + +Calculate the distance to another vector. + +**Arguments:** +- `other`: The other vector + +**Returns:** float: Distance between the two vectors + +#### `dot(other: Vector) -> float` + +Calculate the dot product with another vector. + +**Arguments:** +- `other`: The other vector + +**Returns:** float: Dot product of the two vectors + +#### `floor() -> Vector` + +Return a new vector with floored (integer) coordinates. + +Note: + +**Returns:** Vector: New Vector with floor(x) and floor(y) Useful for grid-based positioning. For a hashable tuple, use the .int property instead. + +#### `magnitude() -> float` + +Calculate the length/magnitude of this vector. + +**Returns:** float: The magnitude of the vector + +#### `magnitude_squared() -> float` + +Calculate the squared magnitude of this vector. + +Note: + +**Returns:** float: The squared magnitude (faster than magnitude()) Use this for comparisons to avoid expensive square root calculation. + +#### `normalize() -> Vector` + +Return a unit vector in the same direction. + +Note: + +**Returns:** Vector: New normalized vector with magnitude 1.0 For zero vectors (magnitude 0.0), returns a zero vector rather than raising an exception + +### Window + +Window singleton for accessing and modifying the game window properties + +**Methods:** + +#### `center() -> None` + +Center the window on the screen. + +Note: + +**Returns:** None Only works in windowed mode. Has no effect when fullscreen or in headless mode. + +#### `get() -> Window` + +Get the Window singleton instance. + +Note: + +**Returns:** Window: The global window object This is a class method. Call as Window.get(). There is only one window instance per application. + +#### `screenshot(filename: str = None) -> bytes | None` + +Take a screenshot of the current window contents. + +Note: + +**Arguments:** +- `filename`: Optional path to save screenshot. If omitted, returns raw RGBA bytes. + +**Returns:** bytes | None: Raw RGBA pixel data if no filename given, otherwise None after saving Screenshot is taken at the actual window resolution. Use after render loop update for current frame. + +## Constants + diff --git a/docs/api_reference_dynamic.html b/docs/api_reference_dynamic.html index 14e58f6..d41d591 100644 --- a/docs/api_reference_dynamic.html +++ b/docs/api_reference_dynamic.html @@ -108,7 +108,7 @@

McRogueFace API Reference

-

Generated on 2025-11-29 10:12:05

+

Generated on 2025-12-28 14:29:42

This documentation was dynamically generated from the compiled module.

@@ -126,6 +126,7 @@
  • Drawable
  • Entity
  • EntityCollection
    • +
  • FOV
  • Font
  • Frame
  • Grid
    • @@ -392,6 +393,18 @@ Note:

    Raises: RuntimeError: If a benchmark is already running Benchmark filename is auto-generated from PID and timestamp. Use end_benchmark() to stop and get filename.

    +
    +

    step(dt: float = None) -> float

    +

    Advance simulation time (headless mode only). + +Note:

    +

    Arguments:

    + +

    Returns: float: Actual time advanced in seconds. Returns 0.0 in windowed mode. In windowed mode, this is a no-op and returns 0.0. Use this for deterministic simulation control in headless/testing scenarios.

    +
    +

    Classes

    @@ -424,14 +437,16 @@ Note:

    -
    start(target: UIDrawable) -> None
    +
    start(target: UIDrawable, conflict_mode: str = 'replace') -> None

    Start the animation on a target UI element. Note:

    target: The UI element to animate (Frame, Caption, Sprite, Grid, or Entity)
    +
    conflict_mode: How to handle conflicts if property is already animating: 'replace' (default) - complete existing animation and start new one; 'queue' - wait for existing animation to complete; 'error' - raise RuntimeError if property is busy
    -

    Returns: None The animation will automatically stop if the target is destroyed. Call AnimationManager.update(delta_time) each frame to progress animations.

    +

    Returns: None

    +

    Raises: RuntimeError: When conflict_mode='error' and property is already animating The animation will automatically stop if the target is destroyed.

    @@ -462,7 +477,7 @@ Args: thickness (float, optional): Line thickness. Default: 1.0 Keyword Args: - click (callable): Click handler. Default: None + on_click (callable): Click handler. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 @@ -600,7 +615,7 @@ Args: outline (float, optional): Outline thickness. Default: 0 (no outline) Keyword Args: - click (callable): Click handler. Default: None + on_click (callable): Click handler. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 @@ -709,20 +724,51 @@ Methods: fill(color): Fill entire layer with color

    Methods:

    +
    +
    apply_perspective(entity, visible=None, discovered=None, unknown=None)
    +

    Bind this layer to an entity for automatic FOV updates.

    +
    +
    at(x, y) -> Color

    Get the color at cell position (x, y).

    +
    +
    clear_perspective()
    +

    Remove the perspective binding from this layer.

    +
    + +
    +
    draw_fov(source, radius=None, fov=None, visible=None, discovered=None, unknown=None)
    +

    Paint cells based on field-of-view visibility from source position. + +Note: Layer must be attached to a grid for FOV calculation.

    +
    +
    fill(color)

    Fill the entire layer with the specified color.

    +
    +
    fill_rect(pos, size, color)
    +

    Fill a rectangular region with a color.

    +
    +
    color: Color object or (r, g, b[, a]) tuple
    +
    +
    +
    set(x, y, color)

    Set the color at cell position (x, y).

    + +
    +
    update_perspective()
    +

    Redraw FOV based on the bound entity's current position. +Call this after the entity moves to update the visibility layer.

    +
    @@ -852,6 +898,12 @@ Recomputes which cells are visible from the entity's position and updates the entity's gridstate to track explored areas. This is called automatically when the entity moves if it has a grid with perspective set.

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

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

    +

    Returns: List of Entity objects that are within field of view. Computes FOV from this entity's position and returns all other entities whose positions fall within the visible area.

    +
    @@ -901,6 +953,90 @@ when the entity moves if it has a grid with perspective set.

    +
    +

    FOV

    +

    Inherits from: IntEnum

    +

    Methods:

    + +
    +
    as_integer_ratio(...)
    +

    Return a pair of integers, whose ratio is equal to the original int. +The ratio is in lowest terms and has a positive denominator. +>>> (10).as_integer_ratio() +(10, 1) +>>> (-10).as_integer_ratio() +(-10, 1) +>>> (0).as_integer_ratio() +(0, 1)

    +
    + +
    +
    bit_count(...)
    +

    Number of ones in the binary representation of the absolute value of self. +Also known as the population count. +>>> bin(13) +'0b1101' +>>> (13).bit_count() +3

    +
    + +
    +
    bit_length(...)
    +

    Number of bits necessary to represent self in binary. +>>> bin(37) +'0b100101' +>>> (37).bit_length() +6

    +
    + +
    +
    conjugate(...)
    +

    Returns self, the complex conjugate of any int.

    +
    + +
    +
    from_bytes(...)
    +

    Return the integer represented by the given array of bytes. + bytes + Holds the array of bytes to convert. The argument must either + support the buffer protocol or be an iterable object producing bytes. + Bytes and bytearray are examples of built-in objects that support the + buffer protocol. + byteorder + The byte order used to represent the integer. If byteorder is 'big', + the most significant byte is at the beginning of the byte array. If + byteorder is 'little', the most significant byte is at the end of the + byte array. To request the native byte order of the host system, use + sys.byteorder as the byte order value. Default is to use 'big'. + signed + Indicates whether two's complement is used to represent the integer.

    +
    + +
    +
    is_integer(...)
    +

    Returns True. Exists for duck type compatibility with float.is_integer.

    +
    + +
    +
    to_bytes(...)
    +

    Return an array of bytes representing an integer. + length + Length of bytes object to use. An OverflowError is raised if the + integer is not representable with the given number of bytes. Default + is length 1. + byteorder + The byte order used to represent the integer. If byteorder is 'big', + the most significant byte is at the beginning of the byte array. If + byteorder is 'little', the most significant byte is at the end of the + byte array. To request the native byte order of the host system, use + sys.byteorder as the byte order value. Default is to use 'big'. + signed + Determines whether two's complement is used to represent the integer. + If signed is False and a negative integer is given, an OverflowError + is raised.

    +
    +
    +

    Font

    SFML Font Object

    @@ -1084,6 +1220,17 @@ Attributes:
    +
    +
    entities_in_radius(x: float, y: float, radius: float) -> list[Entity]
    +

    Query entities within radius using spatial hash (O(k) where k = nearby entities).

    +
    +
    x: Center X coordinate
    +
    y: Center Y coordinate
    +
    radius: Search radius
    +
    +

    Returns: List of Entity objects within the radius.

    +
    +
    find_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]

    Find A* path between two points.

    @@ -1201,7 +1348,7 @@ Args: color (Color, optional): Line color. Default: White Keyword Args: - click (callable): Click handler. Default: None + on_click (callable): Click handler. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 @@ -1263,14 +1410,6 @@ Note:

    Returns: None Deactivates the current scene and activates this one. Scene transitions and lifecycle callbacks are triggered.

    -
    -
    get_ui() -> UICollection
    -

    Get the UI element collection for this scene. - -Note:

    -

    Returns: UICollection: Collection of UI elements (Frames, Captions, Sprites, Grids) in this scene Use to add, remove, or iterate over UI elements. Changes are reflected immediately.

    -
    -
    register_keyboard(callback: callable) -> None

    Register a keyboard event handler function. @@ -1279,7 +1418,7 @@ Note:

    callback: Function that receives (key: str, pressed: bool) when keyboard events occur
    -

    Returns: None Alternative to overriding on_keypress() method. Handler is called for both key press and release events.

    +

    Returns: None Alternative to setting on_key property. Handler is called for both key press and release events.

    @@ -1392,6 +1531,11 @@ Methods:

    Fill the entire layer with the specified tile index.

    +
    +
    fill_rect(pos, size, index)
    +

    Fill a rectangular region with a tile index.

    +
    +
    set(x, y, index)

    Set the tile index at cell position (x, y). Use -1 for no tile.

    @@ -1635,19 +1779,6 @@ Note:

    Constants

    diff --git a/docs/mcrfpy.3 b/docs/mcrfpy.3 index 8e4953d..6f9e64b 100644 --- a/docs/mcrfpy.3 +++ b/docs/mcrfpy.3 @@ -14,11 +14,11 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "MCRFPY" "3" "2025-11-29" "McRogueFace dev" "" +.TH "MCRFPY" "3" "2025-12-28" "McRogueFace dev" "" .hy .SH McRogueFace API Reference .PP -\f[I]Generated on 2025-11-29 10:12:05\f[R] +\f[I]Generated on 2025-12-28 14:29:42\f[R] .PP \f[I]This documentation was dynamically generated from the compiled module.\f[R] @@ -47,6 +47,8 @@ Entity .IP \[bu] 2 EntityCollection .IP \[bu] 2 +FOV +.IP \[bu] 2 Font .IP \[bu] 2 Frame @@ -312,6 +314,20 @@ Note: \f[B]Raises:\f[R] RuntimeError: If a benchmark is already running Benchmark filename is auto-generated from PID and timestamp. Use end_benchmark() to stop and get filename. +.SS \f[V]step(dt: float = None) -> float\f[R] +.PP +Advance simulation time (headless mode only). +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]dt\f[R]: Time to advance in seconds. +If None, advances to the next scheduled event (timer/animation). +.PP +\f[B]Returns:\f[R] float: Actual time advanced in seconds. +Returns 0.0 in windowed mode. +In windowed mode, this is a no-op and returns 0.0. +Use this for deterministic simulation control in headless/testing +scenarios. .SS Classes .SS Animation .PP @@ -348,19 +364,24 @@ Note: was destroyed Animations automatically clean up when targets are destroyed. Use this to check if manual cleanup is needed. -.SS \f[V]start(target: UIDrawable) -> None\f[R] +.SS \f[V]start(target: UIDrawable, conflict_mode: str = \[aq]replace\[aq]) -> None\f[R] .PP Start the animation on a target UI element. .PP Note: .PP \f[B]Arguments:\f[R] - \f[V]target\f[R]: The UI element to animate -(Frame, Caption, Sprite, Grid, or Entity) +(Frame, Caption, Sprite, Grid, or Entity) - \f[V]conflict_mode\f[R]: How +to handle conflicts if property is already animating: `replace' +(default) - complete existing animation and start new one; `queue' - +wait for existing animation to complete; `error' - raise RuntimeError if +property is busy .PP -\f[B]Returns:\f[R] None The animation will automatically stop if the -target is destroyed. -Call AnimationManager.update(delta_time) each frame to progress -animations. +\f[B]Returns:\f[R] None +.PP +\f[B]Raises:\f[R] RuntimeError: When conflict_mode=`error' and property +is already animating The animation will automatically stop if the target +is destroyed. .SS \f[V]update(delta_time: float) -> bool\f[R] .PP Update the animation by the given time delta. @@ -390,7 +411,7 @@ Default: 90 color (Color, optional): Arc color. Default: White thickness (float, optional): Line thickness. Default: 1.0 .PP -Keyword Args: click (callable): Click handler. +Keyword Args: on_click (callable): Click handler. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. @@ -507,7 +528,7 @@ Default: White outline_color (Color, optional): Outline color. Default: Transparent outline (float, optional): Outline thickness. Default: 0 (no outline) .PP -Keyword Args: click (callable): Click handler. +Keyword Args: on_click (callable): Click handler. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. @@ -606,15 +627,36 @@ Methods: at(x, y): Get color at cell position set(x, y, color): Set color at cell position fill(color): Fill entire layer with color .PP \f[B]Methods:\f[R] +.SS \f[V]apply_perspective(entity, visible=None, discovered=None, unknown=None)\f[R] +.PP +Bind this layer to an entity for automatic FOV updates. .SS \f[V]at(x, y) -> Color\f[R] .PP Get the color at cell position (x, y). +.SS \f[V]clear_perspective()\f[R] +.PP +Remove the perspective binding from this layer. +.SS \f[V]draw_fov(source, radius=None, fov=None, visible=None, discovered=None, unknown=None)\f[R] +.PP +Paint cells based on field-of-view visibility from source position. +.PP +Note: Layer must be attached to a grid for FOV calculation. .SS \f[V]fill(color)\f[R] .PP Fill the entire layer with the specified color. +.SS \f[V]fill_rect(pos, size, color)\f[R] +.PP +Fill a rectangular region with a color. +.PP +\f[B]Arguments:\f[R] - \f[V]color\f[R]: Color object or (r, g, b[, a]) +tuple .SS \f[V]set(x, y, color)\f[R] .PP Set the color at cell position (x, y). +.SS \f[V]update_perspective()\f[R] +.PP +Redraw FOV based on the bound entity\[cq]s current position. +Call this after the entity moves to update the visibility layer. .SS Drawable .PP Base class for all drawable UI elements @@ -722,6 +764,13 @@ Recomputes which cells are visible from the entity\[cq]s position and updates the entity\[cq]s gridstate to track explored areas. This is called automatically when the entity moves if it has a grid with perspective set. +.SS \f[V]visible_entities(fov=None, radius=None) -> list[Entity]\f[R] +.PP +Get list of other entities visible from this entity\[cq]s position. +.PP +\f[B]Returns:\f[R] List of Entity objects that are within field of view. +Computes FOV from this entity\[cq]s position and returns all other +entities whose positions fall within the visible area. .SS EntityCollection .PP Iterable, indexable collection of Entities @@ -757,6 +806,71 @@ Remove and return entity at index (default: last entity). .PP Remove first occurrence of entity. Raises ValueError if not found. +.SS FOV +.PP +\f[I]Inherits from: IntEnum\f[R] +.PP +\f[B]Methods:\f[R] +.SS \f[V]as_integer_ratio(...)\f[R] +.PP +Return a pair of integers, whose ratio is equal to the original int. +The ratio is in lowest terms and has a positive denominator. +>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10, +1) >>> (0).as_integer_ratio() (0, 1) +.SS \f[V]bit_count(...)\f[R] +.PP +Number of ones in the binary representation of the absolute value of +self. +Also known as the population count. +>>> bin(13) `0b1101' >>> (13).bit_count() 3 +.SS \f[V]bit_length(...)\f[R] +.PP +Number of bits necessary to represent self in binary. +>>> bin(37) `0b100101' >>> (37).bit_length() 6 +.SS \f[V]conjugate(...)\f[R] +.PP +Returns self, the complex conjugate of any int. +.SS \f[V]from_bytes(...)\f[R] +.PP +Return the integer represented by the given array of bytes. +bytes Holds the array of bytes to convert. +The argument must either support the buffer protocol or be an iterable +object producing bytes. +Bytes and bytearray are examples of built-in objects that support the +buffer protocol. +byteorder The byte order used to represent the integer. +If byteorder is `big', the most significant byte is at the beginning of +the byte array. +If byteorder is `little', the most significant byte is at the end of the +byte array. +To request the native byte order of the host system, use sys.byteorder +as the byte order value. +Default is to use `big'. +signed Indicates whether two\[cq]s complement is used to represent the +integer. +.SS \f[V]is_integer(...)\f[R] +.PP +Returns True. +Exists for duck type compatibility with float.is_integer. +.SS \f[V]to_bytes(...)\f[R] +.PP +Return an array of bytes representing an integer. +length Length of bytes object to use. +An OverflowError is raised if the integer is not representable with the +given number of bytes. +Default is length 1. +byteorder The byte order used to represent the integer. +If byteorder is `big', the most significant byte is at the beginning of +the byte array. +If byteorder is `little', the most significant byte is at the end of the +byte array. +To request the native byte order of the host system, use sys.byteorder +as the byte order value. +Default is to use `big'. +signed Determines whether two\[cq]s complement is used to represent the +integer. +If signed is False and a negative integer is given, an OverflowError is +raised. .SS Font .PP SFML Font Object @@ -916,6 +1030,15 @@ Compute field of view from a position. distance (0 = unlimited) - \f[V]light_walls\f[R]: Whether walls are lit when visible - \f[V]algorithm\f[R]: FOV algorithm to use (FOV_BASIC, FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8) +.SS \f[V]entities_in_radius(x: float, y: float, radius: float) -> list[Entity]\f[R] +.PP +Query entities within radius using spatial hash (O(k) where k = nearby +entities). +.PP +\f[B]Arguments:\f[R] - \f[V]x\f[R]: Center X coordinate - \f[V]y\f[R]: +Center Y coordinate - \f[V]radius\f[R]: Search radius +.PP +\f[B]Returns:\f[R] List of Entity objects within the radius. .SS \f[V]find_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]\f[R] .PP Find A* path between two points. @@ -1019,7 +1142,7 @@ Default: (0, 0) thickness (float, optional): Line thickness in pixels. Default: 1.0 color (Color, optional): Line color. Default: White .PP -Keyword Args: click (callable): Click handler. +Keyword Args: on_click (callable): Click handler. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. @@ -1071,16 +1194,6 @@ Note: \f[B]Returns:\f[R] None Deactivates the current scene and activates this one. Scene transitions and lifecycle callbacks are triggered. -.SS \f[V]get_ui() -> UICollection\f[R] -.PP -Get the UI element collection for this scene. -.PP -Note: -.PP -\f[B]Returns:\f[R] UICollection: Collection of UI elements (Frames, -Captions, Sprites, Grids) in this scene Use to add, remove, or iterate -over UI elements. -Changes are reflected immediately. .SS \f[V]register_keyboard(callback: callable) -> None\f[R] .PP Register a keyboard event handler function. @@ -1090,7 +1203,7 @@ Note: \f[B]Arguments:\f[R] - \f[V]callback\f[R]: Function that receives (key: str, pressed: bool) when keyboard events occur .PP -\f[B]Returns:\f[R] None Alternative to overriding on_keypress() method. +\f[B]Returns:\f[R] None Alternative to setting on_key property. Handler is called for both key press and release events. .SS Sprite .PP @@ -1187,6 +1300,9 @@ Returns -1 if no tile. .SS \f[V]fill(index)\f[R] .PP Fill the entire layer with the specified tile index. +.SS \f[V]fill_rect(pos, size, index)\f[R] +.PP +Fill a rectangular region with a tile index. .SS \f[V]set(x, y, index)\f[R] .PP Set the tile index at cell position (x, y). @@ -1410,29 +1526,3 @@ given, otherwise None after saving Screenshot is taken at the actual window resolution. Use after render loop update for current frame. .SS Constants -.IP \[bu] 2 -\f[V]FOV_BASIC\f[R] (int): 0 -.IP \[bu] 2 -\f[V]FOV_DIAMOND\f[R] (int): 1 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_0\f[R] (int): 3 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_1\f[R] (int): 4 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_2\f[R] (int): 5 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_3\f[R] (int): 6 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_4\f[R] (int): 7 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_5\f[R] (int): 8 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_6\f[R] (int): 9 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_7\f[R] (int): 10 -.IP \[bu] 2 -\f[V]FOV_PERMISSIVE_8\f[R] (int): 11 -.IP \[bu] 2 -\f[V]FOV_RESTRICTIVE\f[R] (int): 12 -.IP \[bu] 2 -\f[V]FOV_SHADOW\f[R] (int): 2 diff --git a/src/UIArc.cpp b/src/UIArc.cpp index 6f1c335..62a95c1 100644 --- a/src/UIArc.cpp +++ b/src/UIArc.cpp @@ -463,7 +463,7 @@ int UIArc::init(PyUIArcObject* self, PyObject* args, PyObject* kwds) { static const char* kwlist[] = { "center", "radius", "start_angle", "end_angle", "color", "thickness", - "click", "visible", "opacity", "z_index", "name", + "on_click", "visible", "opacity", "z_index", "name", nullptr }; @@ -511,7 +511,7 @@ int UIArc::init(PyUIArcObject* self, PyObject* args, PyObject* kwds) { // Handle common UIDrawable properties if (click_handler && click_handler != Py_None) { if (!PyCallable_Check(click_handler)) { - PyErr_SetString(PyExc_TypeError, "click must be callable"); + PyErr_SetString(PyExc_TypeError, "on_click must be callable"); return -1; } self->data->click_register(click_handler); diff --git a/src/UIArc.h b/src/UIArc.h index ce9dcf9..12a248c 100644 --- a/src/UIArc.h +++ b/src/UIArc.h @@ -134,7 +134,7 @@ namespace mcrfpydef { " color (Color, optional): Arc color. Default: White\n" " thickness (float, optional): Line thickness. Default: 1.0\n\n" "Keyword Args:\n" - " click (callable): Click handler. Default: None\n" + " on_click (callable): Click handler. Default: None\n" " visible (bool): Visibility state. Default: True\n" " opacity (float): Opacity (0.0-1.0). Default: 1.0\n" " z_index (int): Rendering order. Default: 0\n" diff --git a/src/UICaption.cpp b/src/UICaption.cpp index ba8801e..2434916 100644 --- a/src/UICaption.cpp +++ b/src/UICaption.cpp @@ -331,7 +331,7 @@ int UICaption::init(PyUICaptionObject* self, PyObject* args, PyObject* kwds) static const char* kwlist[] = { "pos", "font", "text", // Positional args (as per spec) // Keyword-only args - "fill_color", "outline_color", "outline", "font_size", "click", + "fill_color", "outline_color", "outline", "font_size", "on_click", "visible", "opacity", "z_index", "name", "x", "y", nullptr }; diff --git a/src/UICircle.cpp b/src/UICircle.cpp index 39e6d94..d190cc4 100644 --- a/src/UICircle.cpp +++ b/src/UICircle.cpp @@ -400,7 +400,7 @@ PyObject* UICircle::repr(PyUICircleObject* self) { int UICircle::init(PyUICircleObject* self, PyObject* args, PyObject* kwds) { static const char* kwlist[] = { "radius", "center", "fill_color", "outline_color", "outline", - "click", "visible", "opacity", "z_index", "name", NULL + "on_click", "visible", "opacity", "z_index", "name", NULL }; float radius = 10.0f; @@ -480,7 +480,7 @@ int UICircle::init(PyUICircleObject* self, PyObject* args, PyObject* kwds) { // Handle common UIDrawable properties if (click_obj && click_obj != Py_None) { if (!PyCallable_Check(click_obj)) { - PyErr_SetString(PyExc_TypeError, "click must be callable"); + PyErr_SetString(PyExc_TypeError, "on_click must be callable"); return -1; } self->data->click_register(click_obj); diff --git a/src/UICircle.h b/src/UICircle.h index c84c1a5..cb9afe8 100644 --- a/src/UICircle.h +++ b/src/UICircle.h @@ -123,7 +123,7 @@ namespace mcrfpydef { " outline_color (Color, optional): Outline color. Default: Transparent\n" " outline (float, optional): Outline thickness. Default: 0 (no outline)\n\n" "Keyword Args:\n" - " click (callable): Click handler. Default: None\n" + " on_click (callable): Click handler. Default: None\n" " visible (bool): Visibility state. Default: True\n" " opacity (float): Opacity (0.0-1.0). Default: 1.0\n" " z_index (int): Rendering order. Default: 0\n" diff --git a/src/UIFrame.cpp b/src/UIFrame.cpp index 9db3503..4a74123 100644 --- a/src/UIFrame.cpp +++ b/src/UIFrame.cpp @@ -504,7 +504,7 @@ int UIFrame::init(PyUIFrameObject* self, PyObject* args, PyObject* kwds) static const char* kwlist[] = { "pos", "size", // Positional args (as per spec) // Keyword-only args - "fill_color", "outline_color", "outline", "children", "click", + "fill_color", "outline_color", "outline", "children", "on_click", "visible", "opacity", "z_index", "name", "x", "y", "w", "h", "clip_children", "cache_subtree", nullptr }; diff --git a/src/UIGrid.cpp b/src/UIGrid.cpp index b58fcec..e56ed5d 100644 --- a/src/UIGrid.cpp +++ b/src/UIGrid.cpp @@ -749,7 +749,7 @@ int UIGrid::init(PyUIGridObject* self, PyObject* args, PyObject* kwds) { static const char* kwlist[] = { "pos", "size", "grid_size", "texture", // Positional args (as per spec) // Keyword-only args - "fill_color", "click", "center_x", "center_y", "zoom", + "fill_color", "on_click", "center_x", "center_y", "zoom", "visible", "opacity", "z_index", "name", "x", "y", "w", "h", "grid_x", "grid_y", "layers", // #150 - layers dict parameter nullptr diff --git a/src/UILine.cpp b/src/UILine.cpp index 4f085b6..7920b6e 100644 --- a/src/UILine.cpp +++ b/src/UILine.cpp @@ -481,7 +481,7 @@ int UILine::init(PyUILineObject* self, PyObject* args, PyObject* kwds) { static const char* kwlist[] = { "start", "end", "thickness", "color", - "click", "visible", "opacity", "z_index", "name", + "on_click", "visible", "opacity", "z_index", "name", nullptr }; @@ -549,7 +549,7 @@ int UILine::init(PyUILineObject* self, PyObject* args, PyObject* kwds) { // Handle click handler if (click_handler && click_handler != Py_None) { if (!PyCallable_Check(click_handler)) { - PyErr_SetString(PyExc_TypeError, "click must be callable"); + PyErr_SetString(PyExc_TypeError, "on_click must be callable"); return -1; } self->data->click_register(click_handler); diff --git a/src/UILine.h b/src/UILine.h index 3b56847..29f3707 100644 --- a/src/UILine.h +++ b/src/UILine.h @@ -119,7 +119,7 @@ namespace mcrfpydef { " thickness (float, optional): Line thickness in pixels. Default: 1.0\n" " color (Color, optional): Line color. Default: White\n\n" "Keyword Args:\n" - " click (callable): Click handler. Default: None\n" + " on_click (callable): Click handler. Default: None\n" " visible (bool): Visibility state. Default: True\n" " opacity (float): Opacity (0.0-1.0). Default: 1.0\n" " z_index (int): Rendering order. Default: 0\n" diff --git a/src/UISprite.cpp b/src/UISprite.cpp index 58cf3ef..b243360 100644 --- a/src/UISprite.cpp +++ b/src/UISprite.cpp @@ -392,7 +392,7 @@ int UISprite::init(PyUISpriteObject* self, PyObject* args, PyObject* kwds) static const char* kwlist[] = { "pos", "texture", "sprite_index", // Positional args (as per spec) // Keyword-only args - "scale", "scale_x", "scale_y", "click", + "scale", "scale_x", "scale_y", "on_click", "visible", "opacity", "z_index", "name", "x", "y", "snapshot", nullptr }; diff --git a/stubs/mcrfpy.pyi b/stubs/mcrfpy.pyi index be3f6a2..c89e2e8 100644 --- a/stubs/mcrfpy.pyi +++ b/stubs/mcrfpy.pyi @@ -3,12 +3,11 @@ Core game engine interface for creating roguelike games with Python. """ -from typing import Any, List, Dict, Tuple, Optional, Callable, Union, overload, Literal +from typing import Any, List, Dict, Tuple, Optional, Callable, Union, overload # Type aliases -UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid'] +UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid', 'Line', 'Circle', 'Arc'] Transition = Union[str, None] -ConflictMode = Literal['replace', 'queue', 'error'] # Classes @@ -116,9 +115,6 @@ class Frame(Drawable): outline_color: Color outline: float on_click: Optional[Callable[[float, float, int], None]] - on_enter: Optional[Callable[[], None]] - on_exit: Optional[Callable[[], None]] - on_move: Optional[Callable[[float, float], None]] children: 'UICollection' clip_children: bool @@ -142,9 +138,6 @@ class Caption(Drawable): outline_color: Color outline: float on_click: Optional[Callable[[float, float, int], None]] - on_enter: Optional[Callable[[], None]] - on_exit: Optional[Callable[[], None]] - on_move: Optional[Callable[[float, float], None]] w: float # Read-only, computed from text h: float # Read-only, computed from text @@ -165,90 +158,97 @@ class Sprite(Drawable): sprite_index: int scale: float on_click: Optional[Callable[[float, float, int], None]] - on_enter: Optional[Callable[[], None]] - on_exit: Optional[Callable[[], None]] - on_move: Optional[Callable[[float, float], None]] w: float # Read-only, computed from texture h: float # Read-only, computed from texture class Grid(Drawable): - """Grid(pos=None, size=None, grid_size=(20, 20), texture=None, on_click=None, layers=None) + """Grid(x=0, y=0, grid_size=(20, 20), texture=None, tile_width=16, tile_height=16, scale=1.0, on_click=None) A grid-based tilemap UI element for rendering tile-based levels and game worlds. - Supports multiple rendering layers (ColorLayer, TileLayer) and entity management. """ @overload def __init__(self) -> None: ... @overload - def __init__(self, pos: Optional[Tuple[float, float]] = None, - size: Optional[Tuple[float, float]] = None, - grid_size: Tuple[int, int] = (20, 20), - texture: Optional[Texture] = None, - on_click: Optional[Callable] = None, - layers: Optional[Dict[str, str]] = None) -> None: ... + def __init__(self, x: float = 0, y: float = 0, grid_size: Tuple[int, int] = (20, 20), + texture: Optional[Texture] = None, tile_width: int = 16, tile_height: int = 16, + scale: float = 1.0, on_click: Optional[Callable] = None) -> None: ... grid_size: Tuple[int, int] - grid_x: int # Read-only grid width - grid_y: int # Read-only grid height + tile_width: int + tile_height: int texture: Texture - zoom: float - center: Tuple[float, float] - center_x: float - center_y: float - fill_color: Color + scale: float + points: List[List['GridPoint']] entities: 'EntityCollection' - children: 'UICollection' - layers: List[Union['ColorLayer', 'TileLayer']] - hovered_cell: Optional[Tuple[int, int]] - - # Mouse event handlers - on_click: Optional[Callable[[float, float, int], None]] - on_enter: Optional[Callable[[], None]] - on_exit: Optional[Callable[[], None]] - on_move: Optional[Callable[[float, float], None]] - - # Grid cell event handlers - on_cell_click: Optional[Callable[[int, int], None]] - on_cell_enter: Optional[Callable[[int, int], None]] - on_cell_exit: Optional[Callable[[int, int], None]] + background_color: Color + on_click: Optional[Callable[[int, int, int], None]] def at(self, x: int, y: int) -> 'GridPoint': """Get grid point at tile coordinates.""" ... - def add_layer(self, type: str, z_index: int = -1, - texture: Optional[Texture] = None) -> Union['ColorLayer', 'TileLayer']: - """Add a rendering layer. type='color' or 'tile'. z_index<0 = below entities.""" - ... +class Line(Drawable): + """Line(start=None, end=None, thickness=1.0, color=None, on_click=None, **kwargs) - def remove_layer(self, layer: Union['ColorLayer', 'TileLayer']) -> None: - """Remove a layer from the grid.""" - ... + A line UI element for drawing straight lines between two points. + """ - def compute_fov(self, x: int, y: int, radius: int) -> None: - """Compute field of view from a position.""" - ... + @overload + def __init__(self) -> None: ... + @overload + def __init__(self, start: Optional[Tuple[float, float]] = None, + end: Optional[Tuple[float, float]] = None, + thickness: float = 1.0, color: Optional[Color] = None, + on_click: Optional[Callable] = None) -> None: ... - def is_in_fov(self, x: int, y: int) -> bool: - """Check if a cell is visible in the current FOV.""" - ... + start: Vector + end: Vector + thickness: float + color: Color + on_click: Optional[Callable[[float, float, int], None]] - def compute_dijkstra(self, sources: List[Tuple[int, int]], max_cost: float = -1) -> None: - """Compute Dijkstra distance map from source points.""" - ... +class Circle(Drawable): + """Circle(radius=0, center=None, fill_color=None, outline_color=None, outline=0, on_click=None, **kwargs) - def get_dijkstra_distance(self, x: int, y: int) -> float: - """Get distance to nearest source for a cell.""" - ... + A circle UI element for drawing filled or outlined circles. + """ - def get_dijkstra_path(self, x: int, y: int) -> List[Tuple[int, int]]: - """Get path from cell to nearest source.""" - ... + @overload + def __init__(self) -> None: ... + @overload + def __init__(self, radius: float = 0, center: Optional[Tuple[float, float]] = None, + fill_color: Optional[Color] = None, outline_color: Optional[Color] = None, + outline: float = 0, on_click: Optional[Callable] = None) -> None: ... - def find_path(self, x1: int, y1: int, x2: int, y2: int) -> List[Tuple[int, int]]: - """Find A* path between two cells.""" - ... + radius: float + center: Vector + fill_color: Color + outline_color: Color + outline: float + on_click: Optional[Callable[[float, float, int], None]] + +class Arc(Drawable): + """Arc(center=None, radius=0, start_angle=0, end_angle=90, color=None, thickness=1, on_click=None, **kwargs) + + An arc UI element for drawing curved line segments. + """ + + @overload + def __init__(self) -> None: ... + @overload + def __init__(self, center: Optional[Tuple[float, float]] = None, radius: float = 0, + start_angle: float = 0, end_angle: float = 90, + color: Optional[Color] = None, thickness: float = 1.0, + on_click: Optional[Callable] = None) -> None: ... + + center: Vector + radius: float + start_angle: float + end_angle: float + color: Color + thickness: float + on_click: Optional[Callable[[float, float, int], None]] class GridPoint: """Grid point representing a single tile.""" @@ -259,49 +259,10 @@ class GridPoint: class GridPointState: """State information for a grid point.""" - + texture_index: int color: Color -class ColorLayer: - """Grid layer that renders solid colors per cell.""" - - z_index: int - visible: bool - grid_size: Tuple[int, int] - - def fill(self, color: Color) -> None: - """Fill all cells with a color.""" - ... - - def set(self, x: int, y: int, color: Color) -> None: - """Set color at a specific cell.""" - ... - - def at(self, x: int, y: int) -> Color: - """Get color at a specific cell.""" - ... - -class TileLayer: - """Grid layer that renders texture tiles per cell.""" - - z_index: int - visible: bool - texture: Texture - grid_size: Tuple[int, int] - - def fill(self, sprite_index: int) -> None: - """Fill all cells with a sprite index.""" - ... - - def set(self, x: int, y: int, sprite_index: int) -> None: - """Set tile sprite at a specific cell.""" - ... - - def at(self, x: int, y: int) -> int: - """Get tile sprite index at a specific cell.""" - ... - class Entity(Drawable): """Entity(grid_x=0, grid_y=0, texture=None, sprite_index=0, name='') @@ -333,7 +294,7 @@ class Entity(Drawable): ... class UICollection: - """Collection of UI drawable elements (Frame, Caption, Sprite, Grid).""" + """Collection of UI drawable elements (Frame, Caption, Sprite, Grid, Line, Circle, Arc).""" def __len__(self) -> int: ... def __getitem__(self, index: int) -> UIElement: ... @@ -462,19 +423,8 @@ class Animation: duration: float, easing: str = 'linear', loop: bool = False, on_complete: Optional[Callable] = None) -> None: ... - def start(self, target: Any, conflict_mode: ConflictMode = 'replace') -> None: - """Start the animation on a target UI element. - - Args: - target: The UI element to animate (Frame, Caption, Sprite, Grid, or Entity) - conflict_mode: How to handle conflicts if property is already animating: - - 'replace' (default): Complete existing animation and start new one - - 'queue': Wait for existing animation to complete - - 'error': Raise RuntimeError if property is busy - - Raises: - RuntimeError: When conflict_mode='error' and property is already animating - """ + def start(self) -> None: + """Start the animation.""" ... def update(self, dt: float) -> bool: diff --git a/tools/generate_stubs_v2.py b/tools/generate_stubs_v2.py index 5abd852..77e8ddb 100644 --- a/tools/generate_stubs_v2.py +++ b/tools/generate_stubs_v2.py @@ -18,7 +18,7 @@ Core game engine interface for creating roguelike games with Python. from typing import Any, List, Dict, Tuple, Optional, Callable, Union, overload # Type aliases -UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid'] +UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid', 'Line', 'Circle', 'Arc'] Transition = Union[str, None] # Classes @@ -108,84 +108,84 @@ class Drawable: ... class Frame(Drawable): - """Frame(x=0, y=0, w=0, h=0, fill_color=None, outline_color=None, outline=0, click=None, children=None) - + """Frame(x=0, y=0, w=0, h=0, fill_color=None, outline_color=None, outline=0, on_click=None, children=None) + A rectangular frame UI element that can contain other drawable elements. """ - + @overload def __init__(self) -> None: ... @overload def __init__(self, x: float = 0, y: float = 0, w: float = 0, h: float = 0, fill_color: Optional[Color] = None, outline_color: Optional[Color] = None, - outline: float = 0, click: Optional[Callable] = None, + outline: float = 0, on_click: Optional[Callable] = None, children: Optional[List[UIElement]] = None) -> None: ... - + w: float h: float fill_color: Color outline_color: Color outline: float - click: Optional[Callable[[float, float, int], None]] + on_click: Optional[Callable[[float, float, int], None]] children: 'UICollection' clip_children: bool class Caption(Drawable): - """Caption(text='', x=0, y=0, font=None, fill_color=None, outline_color=None, outline=0, click=None) - + """Caption(text='', x=0, y=0, font=None, fill_color=None, outline_color=None, outline=0, on_click=None) + A text display UI element with customizable font and styling. """ - + @overload def __init__(self) -> None: ... @overload def __init__(self, text: str = '', x: float = 0, y: float = 0, font: Optional[Font] = None, fill_color: Optional[Color] = None, outline_color: Optional[Color] = None, outline: float = 0, - click: Optional[Callable] = None) -> None: ... - + on_click: Optional[Callable] = None) -> None: ... + text: str font: Font fill_color: Color outline_color: Color outline: float - click: Optional[Callable[[float, float, int], None]] + on_click: Optional[Callable[[float, float, int], None]] w: float # Read-only, computed from text h: float # Read-only, computed from text class Sprite(Drawable): - """Sprite(x=0, y=0, texture=None, sprite_index=0, scale=1.0, click=None) - + """Sprite(x=0, y=0, texture=None, sprite_index=0, scale=1.0, on_click=None) + A sprite UI element that displays a texture or portion of a texture atlas. """ - + @overload def __init__(self) -> None: ... @overload def __init__(self, x: float = 0, y: float = 0, texture: Optional[Texture] = None, sprite_index: int = 0, scale: float = 1.0, - click: Optional[Callable] = None) -> None: ... - + on_click: Optional[Callable] = None) -> None: ... + texture: Texture sprite_index: int scale: float - click: Optional[Callable[[float, float, int], None]] + on_click: Optional[Callable[[float, float, int], None]] w: float # Read-only, computed from texture h: float # Read-only, computed from texture class Grid(Drawable): - """Grid(x=0, y=0, grid_size=(20, 20), texture=None, tile_width=16, tile_height=16, scale=1.0, click=None) - + """Grid(x=0, y=0, grid_size=(20, 20), texture=None, tile_width=16, tile_height=16, scale=1.0, on_click=None) + A grid-based tilemap UI element for rendering tile-based levels and game worlds. """ - + @overload def __init__(self) -> None: ... @overload def __init__(self, x: float = 0, y: float = 0, grid_size: Tuple[int, int] = (20, 20), texture: Optional[Texture] = None, tile_width: int = 16, tile_height: int = 16, - scale: float = 1.0, click: Optional[Callable] = None) -> None: ... - + scale: float = 1.0, on_click: Optional[Callable] = None) -> None: ... + grid_size: Tuple[int, int] tile_width: int tile_height: int @@ -194,12 +194,74 @@ class Grid(Drawable): points: List[List['GridPoint']] entities: 'EntityCollection' background_color: Color - click: Optional[Callable[[int, int, int], None]] - + on_click: Optional[Callable[[int, int, int], None]] + def at(self, x: int, y: int) -> 'GridPoint': """Get grid point at tile coordinates.""" ... +class Line(Drawable): + """Line(start=None, end=None, thickness=1.0, color=None, on_click=None, **kwargs) + + A line UI element for drawing straight lines between two points. + """ + + @overload + def __init__(self) -> None: ... + @overload + def __init__(self, start: Optional[Tuple[float, float]] = None, + end: Optional[Tuple[float, float]] = None, + thickness: float = 1.0, color: Optional[Color] = None, + on_click: Optional[Callable] = None) -> None: ... + + start: Vector + end: Vector + thickness: float + color: Color + on_click: Optional[Callable[[float, float, int], None]] + +class Circle(Drawable): + """Circle(radius=0, center=None, fill_color=None, outline_color=None, outline=0, on_click=None, **kwargs) + + A circle UI element for drawing filled or outlined circles. + """ + + @overload + def __init__(self) -> None: ... + @overload + def __init__(self, radius: float = 0, center: Optional[Tuple[float, float]] = None, + fill_color: Optional[Color] = None, outline_color: Optional[Color] = None, + outline: float = 0, on_click: Optional[Callable] = None) -> None: ... + + radius: float + center: Vector + fill_color: Color + outline_color: Color + outline: float + on_click: Optional[Callable[[float, float, int], None]] + +class Arc(Drawable): + """Arc(center=None, radius=0, start_angle=0, end_angle=90, color=None, thickness=1, on_click=None, **kwargs) + + An arc UI element for drawing curved line segments. + """ + + @overload + def __init__(self) -> None: ... + @overload + def __init__(self, center: Optional[Tuple[float, float]] = None, radius: float = 0, + start_angle: float = 0, end_angle: float = 90, + color: Optional[Color] = None, thickness: float = 1.0, + on_click: Optional[Callable] = None) -> None: ... + + center: Vector + radius: float + start_angle: float + end_angle: float + color: Color + thickness: float + on_click: Optional[Callable[[float, float, int], None]] + class GridPoint: """Grid point representing a single tile.""" @@ -244,7 +306,7 @@ class Entity(Drawable): ... class UICollection: - """Collection of UI drawable elements (Frame, Caption, Sprite, Grid).""" + """Collection of UI drawable elements (Frame, Caption, Sprite, Grid, Line, Circle, Arc).""" def __len__(self) -> int: ... def __getitem__(self, index: int) -> UIElement: ...