[Documentation] Update Grid stubs to match current API #161

New issue

Closed

opened 2025-12-28 20:30:53 +00:00 by john · 0 comments

john commented

2025-12-28 20:30:53 +00:00

Owner

Summary

The type stubs in stubs/mcrfpy.pyi have outdated Grid and GridPoint definitions that don't match the current API.

Incorrect Stub Definitions

Grid Constructor

Stubs say:

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: ...

Actual API:

def __init__(self, pos: Tuple[float, float] = (0, 0), 
             grid_size: Tuple[int, int] = (2, 2),
             size: Tuple[float, float] = (32, 32),
             texture: Optional[Texture] = None,
             on_click: Optional[Callable] = None) -> None: ...

Changes needed:

x, y → pos=(x, y) tuple
tile_width, tile_height, scale → size=(w, h) tuple + zoom property
Default grid_size is (2, 2) not (20, 20)

Grid Properties

Missing from stubs:

zoom: float - scale factor for rendering
fill_color: Color - grid background color
center: Vector - viewport center point
center_x, center_y: float - viewport center components
perspective: bool - perspective rendering
perspective_enabled: bool
layers, add_layer(), remove_layer(), layer() - layer system
fov, fov_radius, is_in_fov(), compute_fov() - field of view
compute_dijkstra(), get_dijkstra_path(), get_dijkstra_distance() - pathfinding
compute_astar_path(), find_path() - A* pathfinding
entities_in_radius() - spatial query
hovered_cell - mouse interaction
on_cell_click, on_cell_enter, on_cell_exit - cell-level events

GridPoint

Stubs say:

class GridPoint:
    texture_index: int
    solid: bool
    color: Color

Actual API:

class GridPoint:
    walkable: bool
    transparent: bool
    entities: EntityCollection  # Read-only

No texture_index, solid, or color properties exist.

GridPointState

Stubs say:

class GridPointState:
    texture_index: int
    color: Color

Actual API:

class GridPointState:
    visible: bool
    discovered: bool

Completely different purpose - tracks FOV state, not tile appearance.

Discovered while implementing #143 (Focus System Demo)
Stubs generator is at tools/generate_stubs_v2.py

## Summary The type stubs in `stubs/mcrfpy.pyi` have outdated Grid and GridPoint definitions that don't match the current API. ## Incorrect Stub Definitions ### Grid Constructor **Stubs say:** ```python 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: ... ``` **Actual API:** ```python def __init__(self, pos: Tuple[float, float] = (0, 0), grid_size: Tuple[int, int] = (2, 2), size: Tuple[float, float] = (32, 32), texture: Optional[Texture] = None, on_click: Optional[Callable] = None) -> None: ... ``` **Changes needed:** - `x, y` → `pos=(x, y)` tuple - `tile_width, tile_height, scale` → `size=(w, h)` tuple + `zoom` property - Default `grid_size` is `(2, 2)` not `(20, 20)` ### Grid Properties **Missing from stubs:** - `zoom: float` - scale factor for rendering - `fill_color: Color` - grid background color - `center: Vector` - viewport center point - `center_x, center_y: float` - viewport center components - `perspective: bool` - perspective rendering - `perspective_enabled: bool` - `layers`, `add_layer()`, `remove_layer()`, `layer()` - layer system - `fov`, `fov_radius`, `is_in_fov()`, `compute_fov()` - field of view - `compute_dijkstra()`, `get_dijkstra_path()`, `get_dijkstra_distance()` - pathfinding - `compute_astar_path()`, `find_path()` - A* pathfinding - `entities_in_radius()` - spatial query - `hovered_cell` - mouse interaction - `on_cell_click`, `on_cell_enter`, `on_cell_exit` - cell-level events ### GridPoint **Stubs say:** ```python class GridPoint: texture_index: int solid: bool color: Color ``` **Actual API:** ```python class GridPoint: walkable: bool transparent: bool entities: EntityCollection # Read-only ``` No `texture_index`, `solid`, or `color` properties exist. ### GridPointState **Stubs say:** ```python class GridPointState: texture_index: int color: Color ``` **Actual API:** ```python class GridPointState: visible: bool discovered: bool ``` Completely different purpose - tracks FOV state, not tile appearance. ## Related - Discovered while implementing #143 (Focus System Demo) - Stubs generator is at `tools/generate_stubs_v2.py`