From d761b53d48ac0a4a0c5afa9b681a6f07419b43b5 Mon Sep 17 00:00:00 2001
From: John McCardle Generated on 2025-10-30 21:14:43 Generated on 2025-11-29 10:12:05 This documentation was dynamically generated from the compiled module. Returns: None No error is raised if the timer doesn't exist. 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') Cleanly shut down the game engine and exit the application.
@@ -263,6 +277,19 @@ Note: Returns: None Only one music track can play at a time. Loading new music stops the current track. Add a log message to the current benchmark frame.
+
+Note: Returns: None Raises: RuntimeError: If no benchmark is currently running Messages appear in the 'logs' array of each frame in the output JSON. Play a sound effect using a previously loaded buffer. Raises: KeyError: If the specified scene doesn't exist Enable or disable the developer console overlay.
+
+Note: Returns: None When disabled, the grave/tilde key will not open the console. Use this to ship games without debug features. Set the global music volume. 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 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. 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:
+ 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
+ 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 the element by a relative offset.
+
+Note: Resize the element to new dimensions.
+
+Note: Inherits from: Drawable Resize the element to new dimensions.
+Note: 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:
+ 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
+ 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 the element by a relative offset.
+
+Note: Resize the element to new dimensions.
+
Note: 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 Get the color at cell position (x, y). Fill the entire layer with the specified color. Set the color at cell position (x, y). Base class for all drawable UI elements Add an entity to the end of the collection. Count occurrences of entity in the collection. Add all entities from an iterable to the collection. Find entities by name. Returns: Single entity if exact match, list if wildcard, None if not found. Return index of first occurrence of entity. Raises ValueError if not found. Insert entity at index. Like list.insert(), indices past the end append. Remove and return entity at index (default: last entity). Remove first occurrence of entity. Raises ValueError if not found. Add a new layer to the grid. Returns: The created ColorLayer or TileLayer object. Compute field of view from a position and return visible cells. Compute field of view from a position. Returns: List of tuples (x, y, visible, discovered) for all visible cells: - x, y: Grid coordinates - visible: True (all returned cells are visible) - discovered: True (FOV implies discovery) Also updates the internal FOV state for use with is_in_fov(). Returns: True if the cell is visible, False otherwise Must call compute_fov() first to calculate visibility. Get a layer by its z_index. Returns: The layer with the specified z_index, or None if not found. Move the element by a relative offset.
@@ -896,6 +1155,14 @@ Note: Remove a layer from the grid. Resize the element to new dimensions.
@@ -920,6 +1187,69 @@ Note: 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:
+ 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
+ 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 the element by a relative offset.
+
+Note: Resize the element to new dimensions.
+
+Note: Base class for object-oriented scenes 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 Get the tile index at cell position (x, y). Returns -1 if no tile. Fill the entire layer with the specified tile index. Set the tile index at cell position (x, y). Use -1 for no tile. Timer(name, callback, interval, once=False)
@@ -1106,23 +1475,50 @@ Note: Add an element to the end of the collection. Count occurrences of element in the collection. Add all elements from an iterable to the collection. Find elements by name. Returns: Single element if exact match, list if wildcard, None if not found. Return index of first occurrence of element. Raises ValueError if not found. 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. 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 first occurrence of element. Raises ValueError if not found.McRogueFace API Reference
-
+ end_benchmark() -> strexit() -> None
+ log_benchmark(message: str) -> NoneArguments:
+
+
+ playSound(buffer_id: int) -> None
+ setDevConsole(enabled: bool) -> NoneArguments:
+
+
+ setMusicVolume(volume: int) -> None
+ start_benchmark() -> NoneClasses
Arc
+ Methods:
+
+
+ get_bounds() -> tuple
+ move(dx: float, dy: float) -> None
+ resize(width: float, height: float) -> NoneCaption
resize(width: float, height: float) -> NoneCircle
+ Methods:
+
+
+ get_bounds() -> tuple
+ move(dx: float, dy: float) -> None
+ resize(width: float, height: float) -> NoneColorLayer
+ Methods:
+
+
+ at(x, y) -> Color
+ fill(color)
+ set(x, y, color)Drawable
Methods:
+ append(...)
+ append(entity)
+ count(...)
+ count(entity) -> int
+ extend(...)
+ extend(iterable)
+ index(...)
+ find(name) -> entity or list
+ remove(...)
+ index(entity) -> int
+ insert(index, entity)
+ pop([index]) -> entity
+ remove(entity)Methods:
Methods:
+
+ add_layer(type: str, z_index: int = -1, texture: Texture = None) -> ColorLayer | TileLayerat(...)
- compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> List[Tuple[int, int, bool, bool]]
+ compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None
+ layer(z_index: int) -> ColorLayer | TileLayer | Nonemove(dx: float, dy: float) -> None
+ remove_layer(layer: ColorLayer | TileLayer) -> Noneresize(width: float, height: float) -> NoneMethods:
Line
+ Methods:
+
+
+ get_bounds() -> tuple
+ move(dx: float, dy: float) -> None
+ resize(width: float, height: float) -> NoneScene
Methods:
TileLayer
+ Methods:
+
+
+ at(x, y) -> int
+ fill(index)
+ set(x, y, index)Timer
Methods:
+ append(...)
+ append(element)
+ count(...)
+ count(element) -> int
+ extend(...)
+ extend(iterable)
+ index(...)
+ find(name, recursive=False) -> element or list
+ remove(...)
+ index(element) -> int
+ insert(index, element)
+ pop([index]) -> element
+ remove(element)
Returns: float: Dot product of the two vectors
+floor() -> VectorReturn 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() -> floatCalculate the length/magnitude of this vector.
diff --git a/docs/mcrfpy.3 b/docs/mcrfpy.3 index 5c46cba..8e4953d 100644 --- a/docs/mcrfpy.3 +++ b/docs/mcrfpy.3 @@ -14,11 +14,11 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "MCRFPY" "3" "2025-10-30" "McRogueFace dev" "" +.TH "MCRFPY" "3" "2025-11-29" "McRogueFace dev" "" .hy .SH McRogueFace API Reference .PP -\f[I]Generated on 2025-10-30 20:49:34\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] @@ -31,10 +31,16 @@ Classes .IP \[bu] 2 Animation .IP \[bu] 2 +Arc +.IP \[bu] 2 Caption .IP \[bu] 2 +Circle +.IP \[bu] 2 Color .IP \[bu] 2 +ColorLayer +.IP \[bu] 2 Drawable .IP \[bu] 2 Entity @@ -51,12 +57,16 @@ GridPoint .IP \[bu] 2 GridPointState .IP \[bu] 2 +Line +.IP \[bu] 2 Scene .IP \[bu] 2 Sprite .IP \[bu] 2 Texture .IP \[bu] 2 +TileLayer +.IP \[bu] 2 Timer .IP \[bu] 2 UICollection @@ -110,6 +120,17 @@ Note: .PP \f[B]Returns:\f[R] None No error is raised if the timer doesn\[cq]t exist. +.SS \f[V]end_benchmark() -> str\f[R] +.PP +Stop benchmark capture and write data to JSON file. +.PP +Note: +.PP +\f[B]Returns:\f[R] str: The filename of the written benchmark data +.PP +\f[B]Raises:\f[R] RuntimeError: If no benchmark is currently running +Returns the auto-generated filename (e.g., +`benchmark_12345_20250528_143022.json') .SS \f[V]exit() -> None\f[R] .PP Cleanly shut down the game engine and exit the application. @@ -180,6 +201,19 @@ OGG, FLAC) .PP \f[B]Returns:\f[R] None Only one music track can play at a time. Loading new music stops the current track. +.SS \f[V]log_benchmark(message: str) -> None\f[R] +.PP +Add a log message to the current benchmark frame. +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]message\f[R]: Text to associate with the +current frame +.PP +\f[B]Returns:\f[R] None +.PP +\f[B]Raises:\f[R] RuntimeError: If no benchmark is currently running +Messages appear in the `logs' array of each frame in the output JSON. .SS \f[V]playSound(buffer_id: int) -> None\f[R] .PP Play a sound effect using a previously loaded buffer. @@ -201,6 +235,18 @@ If None, uses current scene in the scene .PP \f[B]Raises:\f[R] KeyError: If the specified scene doesn\[cq]t exist +.SS \f[V]setDevConsole(enabled: bool) -> None\f[R] +.PP +Enable or disable the developer console overlay. +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]enabled\f[R]: True to enable the console +(default), False to disable +.PP +\f[B]Returns:\f[R] None When disabled, the grave/tilde key will not open +the console. +Use this to ship games without debug features. .SS \f[V]setMusicVolume(volume: int) -> None\f[R] .PP Set the global music volume. @@ -255,6 +301,17 @@ Note: \f[B]Returns:\f[R] None If a timer with this name exists, it will be replaced. The handler receives the total runtime in seconds as its argument. +.SS \f[V]start_benchmark() -> None\f[R] +.PP +Start capturing benchmark data to a file. +.PP +Note: +.PP +\f[B]Returns:\f[R] None +.PP +\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 Classes .SS Animation .PP @@ -316,6 +373,62 @@ update in seconds \f[B]Returns:\f[R] bool: True if animation is still running, False if complete Typically called by AnimationManager automatically. Manual calls only needed for custom animation control. +.SS Arc +.PP +\f[I]Inherits from: Drawable\f[R] +.PP +Arc(center=None, radius=0, start_angle=0, end_angle=90, color=None, +thickness=1, **kwargs) +.PP +An arc UI element for drawing curved line segments. +.PP +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 +.PP +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. +Default: 0 name (str): Element name for finding. +Default: None +.PP +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 +.PP +\f[B]Methods:\f[R] +.SS \f[V]get_bounds() -> tuple\f[R] +.PP +Get the bounding rectangle of this drawable element. +.PP +Note: +.PP +\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the +element\[cq]s bounds The bounds are in screen coordinates and account +for current position and size. +.SS \f[V]move(dx: float, dy: float) -> None\f[R] +.PP +Move the element by a relative offset. +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels - +\f[V]dy\f[R]: Vertical offset in pixels +.SS \f[V]resize(width: float, height: float) -> None\f[R] +.PP +Resize the element to new dimensions. +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels - +\f[V]height\f[R]: New height in pixels .SS Caption .PP \f[I]Inherits from: Drawable\f[R] @@ -378,6 +491,61 @@ Note: .PP \f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels - \f[V]height\f[R]: New height in pixels +.SS Circle +.PP +\f[I]Inherits from: Drawable\f[R] +.PP +Circle(radius=0, center=None, fill_color=None, outline_color=None, +outline=0, **kwargs) +.PP +A circle UI element for drawing filled or outlined circles. +.PP +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) +.PP +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. +Default: 0 name (str): Element name for finding. +Default: None +.PP +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 +.PP +\f[B]Methods:\f[R] +.SS \f[V]get_bounds() -> tuple\f[R] +.PP +Get the bounding rectangle of this drawable element. +.PP +Note: +.PP +\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the +element\[cq]s bounds The bounds are in screen coordinates and account +for current position and size. +.SS \f[V]move(dx: float, dy: float) -> None\f[R] +.PP +Move the element by a relative offset. +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels - +\f[V]dy\f[R]: Vertical offset in pixels +.SS \f[V]resize(width: float, height: float) -> None\f[R] +.PP +Resize the element to new dimensions. +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels - +\f[V]height\f[R]: New height in pixels .SS Color .PP SFML Color Object @@ -419,6 +587,34 @@ Note: \f[B]Returns:\f[R] str: Hex string in format `#RRGGBB' or `#RRGGBBAA' (if alpha < 255) Alpha component is only included if not fully opaque (< 255) +.SS ColorLayer +.PP +ColorLayer(z_index=-1, grid_size=None) +.PP +A grid layer that stores RGBA colors per cell. +.PP +Args: z_index (int): Render order. +Negative = below entities. +Default: -1 grid_size (tuple): Dimensions as (width, height). +Default: parent grid size +.PP +Attributes: z_index (int): Layer z-order relative to entities visible +(bool): Whether layer is rendered grid_size (tuple): Layer dimensions +(read-only) +.PP +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]at(x, y) -> Color\f[R] +.PP +Get the color at cell position (x, y). +.SS \f[V]fill(color)\f[R] +.PP +Fill the entire layer with the specified color. +.SS \f[V]set(x, y, color)\f[R] +.PP +Set the color at cell position (x, y). .SS Drawable .PP Base class for all drawable UI elements @@ -531,11 +727,36 @@ perspective set. Iterable, indexable collection of Entities .PP \f[B]Methods:\f[R] -.SS \f[V]append(...)\f[R] -.SS \f[V]count(...)\f[R] -.SS \f[V]extend(...)\f[R] -.SS \f[V]index(...)\f[R] -.SS \f[V]remove(...)\f[R] +.SS \f[V]append(entity)\f[R] +.PP +Add an entity to the end of the collection. +.SS \f[V]count(entity) -> int\f[R] +.PP +Count occurrences of entity in the collection. +.SS \f[V]extend(iterable)\f[R] +.PP +Add all entities from an iterable to the collection. +.SS \f[V]find(name) -> entity or list\f[R] +.PP +Find entities by name. +.PP +\f[B]Returns:\f[R] Single entity if exact match, list if wildcard, None +if not found. +.SS \f[V]index(entity) -> int\f[R] +.PP +Return index of first occurrence of entity. +Raises ValueError if not found. +.SS \f[V]insert(index, entity)\f[R] +.PP +Insert entity at index. +Like list.insert(), indices past the end append. +.SS \f[V]pop([index]) -> entity\f[R] +.PP +Remove and return entity at index (default: last entity). +.SS \f[V]remove(entity)\f[R] +.PP +Remove first occurrence of entity. +Raises ValueError if not found. .SS Font .PP SFML Font Object @@ -568,6 +789,8 @@ 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 .PP Attributes: x, y (float): Position in pixels w, h (float): Size in @@ -577,7 +800,7 @@ 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 +frame bounds cache_subtree (bool): Cache subtree rendering to texture .PP \f[B]Methods:\f[R] .SS \f[V]get_bounds() -> tuple\f[R] @@ -653,6 +876,17 @@ visible (bool): Visibility state opacity (float): Opacity value z_index (int): Rendering order name (str): Element name .PP \f[B]Methods:\f[R] +.SS \f[V]add_layer(type: str, z_index: int = -1, texture: Texture = None) -> ColorLayer | TileLayer\f[R] +.PP +Add a new layer to the grid. +.PP +\f[B]Arguments:\f[R] - \f[V]type\f[R]: Layer type (`color' or `tile') - +\f[V]z_index\f[R]: Render order. +Negative = below entities, >= 0 = above entities. +Default: -1 - \f[V]texture\f[R]: Texture for tile layers. +Required for `tile' type. +.PP +\f[B]Returns:\f[R] The created ColorLayer or TileLayer object. .SS \f[V]at(...)\f[R] .SS \f[V]compute_astar_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]\f[R] .PP @@ -673,20 +907,15 @@ Compute Dijkstra map from root position. \f[B]Arguments:\f[R] - \f[V]root_x\f[R]: X coordinate of the root/target - \f[V]root_y\f[R]: Y coordinate of the root/target - \f[V]diagonal_cost\f[R]: Cost of diagonal movement (default: 1.41) -.SS \f[V]compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> List[Tuple[int, int, bool, bool]]\f[R] +.SS \f[V]compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None\f[R] .PP -Compute field of view from a position and return visible cells. +Compute field of view from a position. .PP \f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate of the viewer - \f[V]y\f[R]: Y coordinate of the viewer - \f[V]radius\f[R]: Maximum view 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) -.PP -\f[B]Returns:\f[R] List of tuples (x, y, visible, discovered) for all -visible cells: - x, y: Grid coordinates - visible: True (all returned -cells are visible) - discovered: True (FOV implies discovery) Also -updates the internal FOV state for use with is_in_fov(). .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. @@ -736,6 +965,15 @@ Y coordinate to check .PP \f[B]Returns:\f[R] True if the cell is visible, False otherwise Must call compute_fov() first to calculate visibility. +.SS \f[V]layer(z_index: int) -> ColorLayer | TileLayer | None\f[R] +.PP +Get a layer by its z_index. +.PP +\f[B]Arguments:\f[R] - \f[V]z_index\f[R]: The z_index of the layer to +find. +.PP +\f[B]Returns:\f[R] The layer with the specified z_index, or None if not +found. .SS \f[V]move(dx: float, dy: float) -> None\f[R] .PP Move the element by a relative offset. @@ -744,6 +982,11 @@ Note: .PP \f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels - \f[V]dy\f[R]: Vertical offset in pixels +.SS \f[V]remove_layer(layer: ColorLayer | TileLayer) -> None\f[R] +.PP +Remove a layer from the grid. +.PP +\f[B]Arguments:\f[R] - \f[V]layer\f[R]: The layer to remove. .SS \f[V]resize(width: float, height: float) -> None\f[R] .PP Resize the element to new dimensions. @@ -762,6 +1005,58 @@ UIGridPoint object UIGridPointState object .PP \f[B]Methods:\f[R] +.SS Line +.PP +\f[I]Inherits from: Drawable\f[R] +.PP +Line(start=None, end=None, thickness=1.0, color=None, **kwargs) +.PP +A line UI element for drawing straight lines between two points. +.PP +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 +.PP +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. +Default: 0 name (str): Element name for finding. +Default: None +.PP +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 +.PP +\f[B]Methods:\f[R] +.SS \f[V]get_bounds() -> tuple\f[R] +.PP +Get the bounding rectangle of this drawable element. +.PP +Note: +.PP +\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the +element\[cq]s bounds The bounds are in screen coordinates and account +for current position and size. +.SS \f[V]move(dx: float, dy: float) -> None\f[R] +.PP +Move the element by a relative offset. +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels - +\f[V]dy\f[R]: Vertical offset in pixels +.SS \f[V]resize(width: float, height: float) -> None\f[R] +.PP +Resize the element to new dimensions. +.PP +Note: +.PP +\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels - +\f[V]height\f[R]: New height in pixels .SS Scene .PP Base class for object-oriented scenes @@ -864,6 +1159,38 @@ Note: SFML Texture Object .PP \f[B]Methods:\f[R] +.SS TileLayer +.PP +TileLayer(z_index=-1, texture=None, grid_size=None) +.PP +A grid layer that stores sprite indices per cell. +.PP +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 +.PP +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) +.PP +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 +.PP +\f[B]Methods:\f[R] +.SS \f[V]at(x, y) -> int\f[R] +.PP +Get the tile index at cell position (x, y). +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]set(x, y, index)\f[R] +.PP +Set the tile index at cell position (x, y). +Use -1 for no tile. .SS Timer .PP Timer(name, callback, interval, once=False) @@ -937,11 +1264,43 @@ Timer will fire after the remaining time elapses. Iterable, indexable collection of UI objects .PP \f[B]Methods:\f[R] -.SS \f[V]append(...)\f[R] -.SS \f[V]count(...)\f[R] -.SS \f[V]extend(...)\f[R] -.SS \f[V]index(...)\f[R] -.SS \f[V]remove(...)\f[R] +.SS \f[V]append(element)\f[R] +.PP +Add an element to the end of the collection. +.SS \f[V]count(element) -> int\f[R] +.PP +Count occurrences of element in the collection. +.SS \f[V]extend(iterable)\f[R] +.PP +Add all elements from an iterable to the collection. +.SS \f[V]find(name, recursive=False) -> element or list\f[R] +.PP +Find elements by name. +.PP +\f[B]Returns:\f[R] Single element if exact match, list if wildcard, None +if not found. +.SS \f[V]index(element) -> int\f[R] +.PP +Return index of first occurrence of element. +Raises ValueError if not found. +.SS \f[V]insert(index, element)\f[R] +.PP +Insert element at index. +Like list.insert(), indices past the end append. +.PP +Note: If using z_index for sorting, insertion order may not persist +after the next render. +Use name-based .find() for stable element access. +.SS \f[V]pop([index]) -> element\f[R] +.PP +Remove and return element at index (default: last element). +.PP +Note: If using z_index for sorting, indices may shift after render. +Use name-based .find() for stable element access. +.SS \f[V]remove(element)\f[R] +.PP +Remove first occurrence of element. +Raises ValueError if not found. .SS UICollectionIter .PP Iterator for a collection of UI objects @@ -981,6 +1340,15 @@ Calculate the dot product with another vector. \f[B]Arguments:\f[R] - \f[V]other\f[R]: The other vector .PP \f[B]Returns:\f[R] float: Dot product of the two vectors +.SS \f[V]floor() -> Vector\f[R] +.PP +Return a new vector with floored (integer) coordinates. +.PP +Note: +.PP +\f[B]Returns:\f[R] Vector: New Vector with floor(x) and floor(y) Useful +for grid-based positioning. +For a hashable tuple, use the .int property instead. .SS \f[V]magnitude() -> float\f[R] .PP Calculate the length/magnitude of this vector. diff --git a/stubs/mcrfpy.pyi b/stubs/mcrfpy.pyi index 919794b..b6654fa 100644 --- a/stubs/mcrfpy.pyi +++ b/stubs/mcrfpy.pyi @@ -96,98 +96,159 @@ 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]] + on_enter: Optional[Callable[[], None]] + on_exit: Optional[Callable[[], None]] + on_move: Optional[Callable[[float, float], 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]] + 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 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]] + 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, 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, 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 - 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.""" ... + 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.""" + ... + + def remove_layer(self, layer: Union['ColorLayer', 'TileLayer']) -> None: + """Remove a layer from the grid.""" + ... + + def compute_fov(self, x: int, y: int, radius: int) -> None: + """Compute field of view from a position.""" + ... + + def is_in_fov(self, x: int, y: int) -> bool: + """Check if a cell is visible in the current FOV.""" + ... + + def compute_dijkstra(self, sources: List[Tuple[int, int]], max_cost: float = -1) -> None: + """Compute Dijkstra distance map from source points.""" + ... + + def get_dijkstra_distance(self, x: int, y: int) -> float: + """Get distance to nearest source for a cell.""" + ... + + def get_dijkstra_path(self, x: int, y: int) -> List[Tuple[int, int]]: + """Get path from cell to nearest source.""" + ... + + 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.""" @@ -197,10 +258,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='') diff --git a/tests/demo/screens/grid_demo.py b/tests/demo/screens/grid_demo.py index 1797885..434c139 100644 --- a/tests/demo/screens/grid_demo.py +++ b/tests/demo/screens/grid_demo.py @@ -8,29 +8,33 @@ class GridDemo(DemoScreen): def setup(self): self.add_title("Grid System") - self.add_description("Tile-based rendering with camera, zoom, and children support") + self.add_description("Multi-layer rendering with camera, zoom, and children support") - # Create a grid - grid = mcrfpy.Grid(grid_size=(15, 10), pos=(50, 120), size=(400, 280)) + # Create a grid with no default layers + grid = mcrfpy.Grid(grid_size=(15, 10), pos=(50, 120), size=(400, 280), layers={}) grid.fill_color = mcrfpy.Color(20, 20, 40) + + # Add a color layer for the checkerboard pattern (z_index=-1 = below entities) + color_layer = grid.add_layer("color", z_index=-1) + # Center camera on middle of grid (in pixel coordinates: cells * cell_size / 2) # For 15x10 grid with 16x16 cells: center = (15*16/2, 10*16/2) = (120, 80) grid.center = (120, 80) self.ui.append(grid) - # Set some tile colors to create a pattern + # Set tile colors via the color layer to create a pattern for x in range(15): for y in range(10): point = grid.at(x, y) # Checkerboard pattern if (x + y) % 2 == 0: - point.color = mcrfpy.Color(40, 40, 60) + color_layer.set(x, y, mcrfpy.Color(40, 40, 60)) else: - point.color = mcrfpy.Color(30, 30, 50) + color_layer.set(x, y, mcrfpy.Color(30, 30, 50)) # Border if x == 0 or x == 14 or y == 0 or y == 9: - point.color = mcrfpy.Color(80, 60, 40) + color_layer.set(x, y, mcrfpy.Color(80, 60, 40)) point.walkable = False # Add some children to the grid @@ -53,13 +57,12 @@ class GridDemo(DemoScreen): props = [ "grid_size: (15, 10)", - "zoom: 1.0", + "layers: [ColorLayer]", "center: (120, 80)", - "fill_color: dark blue", "", "Features:", + "- Multi-layer rendering", "- Camera pan/zoom", - "- Tile colors", "- Children collection", "- FOV/pathfinding", ] @@ -69,8 +72,9 @@ class GridDemo(DemoScreen): info.children.append(cap) # Code example - code = """# Grid with children -grid = mcrfpy.Grid(grid_size=(20, 15), pos=(50, 50), size=(320, 240)) -grid.at(5, 5).color = mcrfpy.Color(255, 0, 0) # Red tile + code = """# Grid with layers +grid = mcrfpy.Grid(grid_size=(20, 15), pos=(50, 50), size=(320, 240), layers={}) +layer = grid.add_layer("color", z_index=-1) # Below entities +layer.set(5, 5, mcrfpy.Color(255, 0, 0)) # Red tile grid.children.append(mcrfpy.Caption("Label", pos=(80, 48)))""" self.add_code_example(code, y=420) diff --git a/tests/demo/screenshots/demo_03_grid_system.png b/tests/demo/screenshots/demo_03_grid_system.png index 14880010737cebcbeaf10e0337887e787ea30e3a..3f2469572d252cb67fd5ad559a98fb1e8a1034e1 100644 GIT binary patch delta 52685 zcma&Oc|4TeA3uD}V#YEI*=FoQQpwnNW>TmmZIYz1#3Z4j?AMH8s1&6rktuFzQHqeH zVI(3(QL;rL3JF=V{f^XK_xJfdujlz^Ue~MT+Rizj^WHvJNijP513FO!NvgfCmWYSx zh3p=
zIbCVIcR|UJVG_oc u#DhOp
zi2P@Jo)Lu(%gIWq--YAiXz|%8e~MS5sFE?dv-A;V(m{yd)~)!+N4X6Xpnw_I;+4aIHScCyQUX1HT-_gk@7I%eB<93zl#L#e5^
z2st6b%KGiT{$K05`uj1iVhEWgD4j@h4&SDQ*3*OI2?oBGbY-%B4Jcg325SK$!UjUrH#VCi?BAaA;|TPH^GUHnAAl^mG}jrzl(u)zCmt81c*3$F8*-
zXh8Ae5~7=)L)Afcw4Yl6U;sQeRsk0j6acfDJnu8MTnR`|k9g=%%!bW-%*}y_Ns8Pe
zNLJ><@zA#@D!S~L?Jj%2CO(E5k5)udP?}`m-)bsytu>|rvm4rOySb|3wg>7;$1BJ{
z@^CO9Bq?bxOlR;+qsRb((2!mH#ANaf9@nCStm6y)Dl7|b5s@9VHFeLLU%X%zu*5Js
zy9l6qJtk1l$&*JWxF~?+V%X`Dmw>}-9eKzJ#4wTe9dd_~d;$Z%R>#>RbpKyqjcT=A
z7OJ@=c7Pe@@Jq`<_HV}?!2739o;LVjyw4>4R0JpDK2sC1SbP3%z-_w8528jj{mM_k
zC$w(tXJeBcI8YvW&i>rg*IJF7P=hl8V!OwFG@pVkEbhZ}_hBHvbLAHlL^b}&a0r)W
z*TnES9EBW$Qp*=mpDSgX_4W1PTMJ^rAJOJ2gEaOm4C%r4g@sO=Ztf|S$qYCx2Jl%3
zgp+n+IHG}SmiW79la^D$Z`?B}bMI1{Z9V_C`tY~)61wN#^9a0RGj<+o>p`7Xn6yQ;
z@746;C)@I(n|rBErq_PI*2bh%Tn28ft5u^MM*{{JP20BKuO4y}6>a;$|7_{}1a9T*
zUKf{nWYy@tZkC?2qgK9D&!2TdFIhC_5sSF{zBT6bU#$5boz{O9_-MI+)s>_7%LI#+
zq}}iZCvX~gO(9;_Z@S#%V+^+8IypXd8}(jD!yiDiaQl+!w$%+wj9BeKe(KizA?IJ1
z^D5r)M#$qn;{v1n(FzJzW-B`I?+2a+$qT0A|F(92Ue$4-+K)w@Jh`*<4GA|!nYoj9
zz2EwL8YNeXe9A+jq+2Rj6l#ig)4JyuG0PjozIl)av4~u-5eS7S=UWB%h2|az*e$VF
zw<##_Xv?(S!^J&Co`=ag!6nZ?XqMa)6X2+>8sMe#+3<52Wf5ZA1SGcCEMPoTo?$`a
zXl85Bzu`ONfOTM7;Xikz+8AoPfstw##pAJt?$W^rUS7E(GO;VtiYBx^7cS_91OHBa
zqKmMwa0}Eq%bO?@9?m|25|1-W8F`}vrP<7Z)XhH&fZVaTu%q8r;OVb;HI(zZTBnk-
zoqV^7&1tqu=v06H@)yO#%GQa2n~F=CyLxPH{ok$hUs7hB)Iw#)l4nCXMH`smb4X
zEkL?V!{pXoYR~(`QQ|0Rd(#u)nr!*Nia$G;+LLF!NB8U3n7TXLu$j6M?!*u
zbTnyaQBr&pVo7LQ30;OEp~aStyooKC>GfsBXtH_o(w^=AL7l7B^Sjn!P!}=G5m3sV
z%aa^~SEtZ5cwJi#1XTOc)gV58N`lFkozPbrV$7||tya;@&_HqxGPi5K>+r$^y$vAK
z89rRiYcw?8BvlHWTfEQvVz~sPA^GPd>hyA#y&n!A0MZO%^3$@_7zp@VRne$uOu@J3
zY7sI$^570Qt>JfLZXb!#8uW^!k3DTGQvGjy1`w$BxmTs(MCTtd(|rBTA*|`+{4t{h42JbS%+}A0X$p@V
zQ5)X{d54wKrZz-Uh@_4&=`%W&4aQHBCr$h#2QdD?S{*GCi#ukIaB;a0$Uw-yoHCA3
zN