Circle drawing primitives for range visualization #129

New Issue

john · 2025-10-31T02:49:04Z

john commented

2025-10-31 02:49:04 +00:00

Feature Request

Add native circle drawing primitives to visualize weapon ranges, sensor ranges, area effects, and other radial mechanics.

Use Case: PINSHIPS Game

The PINSHIPS space roguelike requires:

Weapon range indicators: Show firing range around ships
Sensor range visualization: Detection radius for enemy ships
Explosion/blast radius: Area effect weapons
Planet gravity wells: Circular influence zones

Current Workaround

Highlight grid cells within radius:

# O(n²) check but acceptable for small grids
def highlight_range(grid, center_x, center_y, radius):
    for x in range(center_x - radius, center_x + radius + 1):
        for y in range(center_y - radius, center_y + radius + 1):
            dx, dy = x - center_x, y - center_y
            if dx*dx + dy*dy <= radius*radius:
                grid.at(x, y).bg_color = (255, 0, 0, 64)

Problems with workaround:

O(n²) complexity for each circle
Grid cell granularity (jagged circles)
Not as visually clear as smooth circles
Requires managing grid state

Proposed API

# Filled circle (area effect)
explosion = mcrfpy.Circle(center=(50, 50), radius=15,
                          color=(255, 100, 0, 128), fill=True)
scene.ui.append(explosion)

# Outline circle (range indicator)
weapon_range = mcrfpy.Circle(center=(100, 100), radius=25,
                             color=(255, 0, 0, 128), thickness=2, fill=False)
scene.ui.append(weapon_range)

# Ring (hollow circle)
ring = mcrfpy.Ring(center=(75, 75), inner_radius=10, outer_radius=15,
                   color=(0, 255, 255, 128))
scene.ui.append(ring)

Implementation Notes

Backend: SFML provides sf::CircleShape for efficient circle rendering

UIDrawable Integration:

Create UICircle class inheriting from UIDrawable
Support position, radius, color, fill/outline modes
Implement proper bounding box for culling
Support animation of radius (growing/shrinking effects)

Optional Features:

Ellipse support (non-circular ranges)
Arc segments (partial circles)
Multiple outline/fill colors
Gradient fills

Performance Considerations

Circles are very efficient to render (SFML handles tesselation)
Much faster than per-cell grid updates for large radii
Proper culling keeps off-screen circles from rendering

Priority

Tier 1 Active - Critical for PINSHIPS combat mechanics (Week 2)

Can defer to Week 3 if grid cell workarounds acceptable initially

Complements #128 (Line/Arc drawing) for complete 2D primitive set
Enables strategic visualization (what's in range?)
Foundation for area-effect abilities

Labels

[Major Feature] [priority:tier2-foundation] [system:rendering] [system:ui-hierarchy]

## Feature Request Add native circle drawing primitives to visualize weapon ranges, sensor ranges, area effects, and other radial mechanics. ## Use Case: PINSHIPS Game The PINSHIPS space roguelike requires: - **Weapon range indicators**: Show firing range around ships - **Sensor range visualization**: Detection radius for enemy ships - **Explosion/blast radius**: Area effect weapons - **Planet gravity wells**: Circular influence zones ## Current Workaround Highlight grid cells within radius: ```python # O(n²) check but acceptable for small grids def highlight_range(grid, center_x, center_y, radius): for x in range(center_x - radius, center_x + radius + 1): for y in range(center_y - radius, center_y + radius + 1): dx, dy = x - center_x, y - center_y if dx*dx + dy*dy <= radius*radius: grid.at(x, y).bg_color = (255, 0, 0, 64) ``` **Problems with workaround:** - O(n²) complexity for each circle - Grid cell granularity (jagged circles) - Not as visually clear as smooth circles - Requires managing grid state ## Proposed API ```python # Filled circle (area effect) explosion = mcrfpy.Circle(center=(50, 50), radius=15, color=(255, 100, 0, 128), fill=True) scene.ui.append(explosion) # Outline circle (range indicator) weapon_range = mcrfpy.Circle(center=(100, 100), radius=25, color=(255, 0, 0, 128), thickness=2, fill=False) scene.ui.append(weapon_range) # Ring (hollow circle) ring = mcrfpy.Ring(center=(75, 75), inner_radius=10, outer_radius=15, color=(0, 255, 255, 128)) scene.ui.append(ring) ``` ## Implementation Notes **Backend:** SFML provides `sf::CircleShape` for efficient circle rendering **UIDrawable Integration:** - Create `UICircle` class inheriting from `UIDrawable` - Support position, radius, color, fill/outline modes - Implement proper bounding box for culling - Support animation of radius (growing/shrinking effects) **Optional Features:** - Ellipse support (non-circular ranges) - Arc segments (partial circles) - Multiple outline/fill colors - Gradient fills ## Performance Considerations - Circles are very efficient to render (SFML handles tesselation) - Much faster than per-cell grid updates for large radii - Proper culling keeps off-screen circles from rendering ## Priority **Tier 1 Active** - Critical for PINSHIPS combat mechanics (Week 2) **Can defer to Week 3** if grid cell workarounds acceptable initially ## Related Issues - Complements #128 (Line/Arc drawing) for complete 2D primitive set - Enables strategic visualization (what's in range?) - Foundation for area-effect abilities ## Labels `[Major Feature]` `[priority:tier2-foundation]` `[system:rendering]` `[system:ui-hierarchy]`

john added the

Bugfix

Documentation

priority:tier1-active

priority:tier2-foundation

labels 2025-10-31 12:16:17 +00:00

john removed the

Documentation

Bugfix

priority:tier1-active

priority:tier2-foundation

labels 2025-10-31 12:44:40 +00:00