[Proc Gen] BSP - Core class with splitting #202

New issue

Open

opened 2026-01-12 00:09:56 +00:00 by john · 0 comments

john commented

2026-01-12 00:09:56 +00:00

Owner

Parent Issue: #192

Overview

Implement the core BSP class for binary space partitioning of rectangular regions.

Specification

Constructor

BSP(bounds: tuple[tuple[int, int], tuple[int, int]])

Parameter	Type	Description
`bounds`	`((x, y), (w, h))`	Position and size of the root region.

Properties

Property	Type	Description
`bounds`	`((x, y), (w, h))`	Read-only. Root node bounds.
`root`	`BSPNode`	Read-only. Reference to the root node.

Splitting Methods

def split_once(self, horizontal: bool, position: int) -> BSP

Split the root node once at the specified position.

def split_recursive(self,
                    depth: int,
                    min_size: tuple[int, int],
                    max_ratio: float = 1.5,
                    seed: int = None) -> BSP

Recursively split to the specified depth.

Parameter	Type	Description
`depth`	`int`	Maximum recursion depth. Creates up to 2^depth leaves.
`min_size`	`(int, int)`	Minimum (width, height) for a node to be split.
`max_ratio`	`float`	Maximum aspect ratio before forcing split direction. Default: 1.5.
`seed`	`int`	Random seed. None for random.

def clear(self) -> BSP

Remove all children, keeping only the root node with original bounds.

Implementation Notes

Wrap TCODBsp internally
split_once maps to TCOD_bsp_split_once
split_recursive maps to TCOD_bsp_split_recursive
clear maps to TCOD_bsp_remove_sons
All methods return self for chaining

Acceptance Criteria

BSP can be constructed with bounds tuple
split_once splits at specified position
split_recursive creates proper tree structure
clear removes all children
root property returns valid BSPNode
Unit tests verify tree structure

**Parent Issue:** #192 ## Overview Implement the core `BSP` class for binary space partitioning of rectangular regions. ## Specification ### Constructor ```python BSP(bounds: tuple[tuple[int, int], tuple[int, int]]) ``` | Parameter | Type | Description | |-----------|------|-------------| | `bounds` | `((x, y), (w, h))` | Position and size of the root region. | ### Properties | Property | Type | Description | |----------|------|-------------| | `bounds` | `((x, y), (w, h))` | Read-only. Root node bounds. | | `root` | `BSPNode` | Read-only. Reference to the root node. | ### Splitting Methods ```python def split_once(self, horizontal: bool, position: int) -> BSP ``` Split the root node once at the specified position. ```python def split_recursive(self, depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP ``` Recursively split to the specified depth. | Parameter | Type | Description | |-----------|------|-------------| | `depth` | `int` | Maximum recursion depth. Creates up to 2^depth leaves. | | `min_size` | `(int, int)` | Minimum (width, height) for a node to be split. | | `max_ratio` | `float` | Maximum aspect ratio before forcing split direction. Default: 1.5. | | `seed` | `int` | Random seed. None for random. | ```python def clear(self) -> BSP ``` Remove all children, keeping only the root node with original bounds. ## Implementation Notes - Wrap `TCODBsp` internally - `split_once` maps to `TCOD_bsp_split_once` - `split_recursive` maps to `TCOD_bsp_split_recursive` - `clear` maps to `TCOD_bsp_remove_sons` - All methods return `self` for chaining ## Acceptance Criteria - [ ] `BSP` can be constructed with bounds tuple - [ ] `split_once` splits at specified position - [ ] `split_recursive` creates proper tree structure - [ ] `clear` removes all children - [ ] `root` property returns valid BSPNode - [ ] Unit tests verify tree structure