diff --git a/docs/API_REFERENCE_DYNAMIC.md b/docs/API_REFERENCE_DYNAMIC.md deleted file mode 100644 index 4cf6ae8..0000000 --- a/docs/API_REFERENCE_DYNAMIC.md +++ /dev/null @@ -1,1607 +0,0 @@ -# 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 d41d591..14e58f6 100644 --- a/docs/api_reference_dynamic.html +++ b/docs/api_reference_dynamic.html @@ -108,7 +108,7 @@

McRogueFace API Reference

-

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

+

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

This documentation was dynamically generated from the compiled module.

@@ -126,7 +126,6 @@
  • Drawable
  • Entity
  • EntityCollection
    • -
  • FOV
  • Font
  • Frame
  • Grid
    • @@ -393,18 +392,6 @@ 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

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

    -
    start(target: UIDrawable, conflict_mode: str = 'replace') -> None
    +
    start(target: UIDrawable) -> 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

    -

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

    +

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

    @@ -477,7 +462,7 @@ Args: thickness (float, optional): Line thickness. Default: 1.0 Keyword Args: - on_click (callable): Click handler. Default: None + 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 @@ -615,7 +600,7 @@ Args: outline (float, optional): Outline thickness. Default: 0 (no outline) Keyword Args: - on_click (callable): Click handler. Default: None + 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 @@ -724,51 +709,20 @@ 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.

    -
    @@ -898,12 +852,6 @@ 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.

    -
    @@ -953,90 +901,6 @@ 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

    @@ -1220,17 +1084,6 @@ 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.

    @@ -1348,7 +1201,7 @@ Args: color (Color, optional): Line color. Default: White Keyword Args: - on_click (callable): Click handler. Default: None + 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 @@ -1410,6 +1263,14 @@ 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. @@ -1418,7 +1279,7 @@ Note:

    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.

    +

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

    @@ -1531,11 +1392,6 @@ 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.

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

    Constants

    diff --git a/docs/mcrfpy.3 b/docs/mcrfpy.3 index 6f9e64b..8e4953d 100644 --- a/docs/mcrfpy.3 +++ b/docs/mcrfpy.3 @@ -14,11 +14,11 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "MCRFPY" "3" "2025-12-28" "McRogueFace dev" "" +.TH "MCRFPY" "3" "2025-11-29" "McRogueFace dev" "" .hy .SH McRogueFace API Reference .PP -\f[I]Generated on 2025-12-28 14:29:42\f[R] +\f[I]Generated on 2025-11-29 10:12:05\f[R] .PP \f[I]This documentation was dynamically generated from the compiled module.\f[R] @@ -47,8 +47,6 @@ Entity .IP \[bu] 2 EntityCollection .IP \[bu] 2 -FOV -.IP \[bu] 2 Font .IP \[bu] 2 Frame @@ -314,20 +312,6 @@ 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 @@ -364,24 +348,19 @@ 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, conflict_mode: str = \[aq]replace\[aq]) -> None\f[R] +.SS \f[V]start(target: UIDrawable) -> 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) - \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 +(Frame, Caption, Sprite, Grid, or Entity) .PP -\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. +\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. .SS \f[V]update(delta_time: float) -> bool\f[R] .PP Update the animation by the given time delta. @@ -411,7 +390,7 @@ Default: 90 color (Color, optional): Arc color. Default: White thickness (float, optional): Line thickness. Default: 1.0 .PP -Keyword Args: on_click (callable): Click handler. +Keyword Args: 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. @@ -528,7 +507,7 @@ Default: White outline_color (Color, optional): Outline color. Default: Transparent outline (float, optional): Outline thickness. Default: 0 (no outline) .PP -Keyword Args: on_click (callable): Click handler. +Keyword Args: 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. @@ -627,36 +606,15 @@ 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 @@ -764,13 +722,6 @@ 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 @@ -806,71 +757,6 @@ 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 @@ -1030,15 +916,6 @@ 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. @@ -1142,7 +1019,7 @@ Default: (0, 0) thickness (float, optional): Line thickness in pixels. Default: 1.0 color (Color, optional): Line color. Default: White .PP -Keyword Args: on_click (callable): Click handler. +Keyword Args: 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. @@ -1194,6 +1071,16 @@ 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. @@ -1203,7 +1090,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 setting on_key property. +\f[B]Returns:\f[R] None Alternative to overriding on_keypress() method. Handler is called for both key press and release events. .SS Sprite .PP @@ -1300,9 +1187,6 @@ 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). @@ -1526,3 +1410,29 @@ 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 62a95c1..6f1c335 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", - "on_click", "visible", "opacity", "z_index", "name", + "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, "on_click must be callable"); + PyErr_SetString(PyExc_TypeError, "click must be callable"); return -1; } self->data->click_register(click_handler); diff --git a/src/UIArc.h b/src/UIArc.h index 12a248c..ce9dcf9 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" - " on_click (callable): Click handler. Default: None\n" + " 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 2434916..ba8801e 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", "on_click", + "fill_color", "outline_color", "outline", "font_size", "click", "visible", "opacity", "z_index", "name", "x", "y", nullptr }; diff --git a/src/UICircle.cpp b/src/UICircle.cpp index d190cc4..39e6d94 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", - "on_click", "visible", "opacity", "z_index", "name", NULL + "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, "on_click must be callable"); + PyErr_SetString(PyExc_TypeError, "click must be callable"); return -1; } self->data->click_register(click_obj); diff --git a/src/UICircle.h b/src/UICircle.h index cb9afe8..c84c1a5 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" - " on_click (callable): Click handler. Default: None\n" + " 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 4a74123..9db3503 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", "on_click", + "fill_color", "outline_color", "outline", "children", "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 e56ed5d..b58fcec 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", "on_click", "center_x", "center_y", "zoom", + "fill_color", "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 7920b6e..4f085b6 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", - "on_click", "visible", "opacity", "z_index", "name", + "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, "on_click must be callable"); + PyErr_SetString(PyExc_TypeError, "click must be callable"); return -1; } self->data->click_register(click_handler); diff --git a/src/UILine.h b/src/UILine.h index 29f3707..3b56847 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" - " on_click (callable): Click handler. Default: None\n" + " 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 b243360..58cf3ef 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", "on_click", + "scale", "scale_x", "scale_y", "click", "visible", "opacity", "z_index", "name", "x", "y", "snapshot", nullptr }; diff --git a/stubs/mcrfpy.pyi b/stubs/mcrfpy.pyi index c89e2e8..be3f6a2 100644 --- a/stubs/mcrfpy.pyi +++ b/stubs/mcrfpy.pyi @@ -3,11 +3,12 @@ Core game engine interface for creating roguelike games with Python. """ -from typing import Any, List, Dict, Tuple, Optional, Callable, Union, overload +from typing import Any, List, Dict, Tuple, Optional, Callable, Union, overload, Literal # Type aliases -UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid', 'Line', 'Circle', 'Arc'] +UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid'] Transition = Union[str, None] +ConflictMode = Literal['replace', 'queue', 'error'] # Classes @@ -115,6 +116,9 @@ 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 @@ -138,6 +142,9 @@ 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 @@ -158,97 +165,90 @@ 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(x=0, y=0, grid_size=(20, 20), texture=None, tile_width=16, tile_height=16, scale=1.0, on_click=None) + """Grid(pos=None, size=None, grid_size=(20, 20), texture=None, on_click=None, layers=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, 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: ... + 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: ... grid_size: Tuple[int, int] - tile_width: int - tile_height: int + grid_x: int # Read-only grid width + grid_y: int # Read-only grid height texture: Texture - scale: float - points: List[List['GridPoint']] + zoom: float + center: Tuple[float, float] + center_x: float + center_y: float + fill_color: Color entities: 'EntityCollection' - background_color: Color - on_click: Optional[Callable[[int, int, int], None]] + 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]] 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) + 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.""" + ... - A line UI element for drawing straight lines between two points. - """ + def remove_layer(self, layer: Union['ColorLayer', 'TileLayer']) -> None: + """Remove a layer from the grid.""" + ... - @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 compute_fov(self, x: int, y: int, radius: int) -> None: + """Compute field of view from a position.""" + ... - start: Vector - end: Vector - thickness: float - color: Color - on_click: Optional[Callable[[float, float, int], None]] + def is_in_fov(self, x: int, y: int) -> bool: + """Check if a cell is visible in the current FOV.""" + ... -class Circle(Drawable): - """Circle(radius=0, center=None, fill_color=None, outline_color=None, outline=0, on_click=None, **kwargs) + def compute_dijkstra(self, sources: List[Tuple[int, int]], max_cost: float = -1) -> None: + """Compute Dijkstra distance map from source points.""" + ... - A circle UI element for drawing filled or outlined circles. - """ + def get_dijkstra_distance(self, x: int, y: int) -> float: + """Get distance to nearest source for a cell.""" + ... - @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 get_dijkstra_path(self, x: int, y: int) -> List[Tuple[int, int]]: + """Get path from cell to nearest source.""" + ... - 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]] + def find_path(self, x1: int, y1: int, x2: int, y2: int) -> List[Tuple[int, int]]: + """Find A* path between two cells.""" + ... class GridPoint: """Grid point representing a single tile.""" @@ -259,10 +259,49 @@ 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='') @@ -294,7 +333,7 @@ class Entity(Drawable): ... class UICollection: - """Collection of UI drawable elements (Frame, Caption, Sprite, Grid, Line, Circle, Arc).""" + """Collection of UI drawable elements (Frame, Caption, Sprite, Grid).""" def __len__(self) -> int: ... def __getitem__(self, index: int) -> UIElement: ... @@ -423,8 +462,19 @@ class Animation: duration: float, easing: str = 'linear', loop: bool = False, on_complete: Optional[Callable] = None) -> None: ... - def start(self) -> None: - """Start the animation.""" + 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 update(self, dt: float) -> bool: diff --git a/tools/generate_stubs_v2.py b/tools/generate_stubs_v2.py index 77e8ddb..5abd852 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', 'Line', 'Circle', 'Arc'] +UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid'] 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, on_click=None, children=None) - + """Frame(x=0, y=0, w=0, h=0, fill_color=None, outline_color=None, outline=0, 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, on_click: Optional[Callable] = None, + outline: float = 0, click: Optional[Callable] = None, children: Optional[List[UIElement]] = None) -> None: ... - + w: float h: float fill_color: Color outline_color: Color outline: float - on_click: Optional[Callable[[float, float, int], None]] + 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, on_click=None) - + """Caption(text='', x=0, y=0, font=None, fill_color=None, outline_color=None, outline=0, 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, - on_click: Optional[Callable] = None) -> None: ... - + click: Optional[Callable] = None) -> None: ... + text: str font: Font fill_color: Color outline_color: Color outline: float - on_click: Optional[Callable[[float, float, int], None]] + 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, on_click=None) - + """Sprite(x=0, y=0, texture=None, sprite_index=0, scale=1.0, 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, - on_click: Optional[Callable] = None) -> None: ... - + click: Optional[Callable] = None) -> None: ... + texture: Texture sprite_index: int scale: float - on_click: Optional[Callable[[float, float, int], None]] + 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, on_click=None) - + """Grid(x=0, y=0, grid_size=(20, 20), texture=None, tile_width=16, tile_height=16, scale=1.0, 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, on_click: Optional[Callable] = None) -> None: ... - + scale: float = 1.0, click: Optional[Callable] = None) -> None: ... + grid_size: Tuple[int, int] tile_width: int tile_height: int @@ -194,74 +194,12 @@ class Grid(Drawable): points: List[List['GridPoint']] entities: 'EntityCollection' background_color: Color - on_click: Optional[Callable[[int, int, int], None]] - + 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.""" @@ -306,7 +244,7 @@ class Entity(Drawable): ... class UICollection: - """Collection of UI drawable elements (Frame, Caption, Sprite, Grid, Line, Circle, Arc).""" + """Collection of UI drawable elements (Frame, Caption, Sprite, Grid).""" def __len__(self) -> int: ... def __getitem__(self, index: int) -> UIElement: ...