Enhance Entity rendering and positioning capabilities #233

New issue

Open

opened 2026-02-02 16:22:03 +00:00 by john · 0 comments

john commented

2026-02-02 16:22:03 +00:00

Owner

Overview

This issue tracks enhancements to the entity/grid rendering system to support more flexible sprite sizing and positioning. The current system has several assumptions that limit creative flexibility:

Current Limitations

Single-cell entities: Every entity occupies exactly one grid cell
Uniform sprite sizes: Texture sprite size = grid cell size = entity display size
Fixed origin: Sprites anchor at top-left with no offset support
Point-based queries: FOV and spatial hash treat entities as single points

Proposed Enhancements

The following sub-issues break down the work:

Entity origin offset - Allow entities to render with pixel offset from their tile position (e.g., 16×24 sprite on 16×16 grid with origin at (0,8))
Texture display bounds - Support textures where sprite content doesn't fill the entire cell (e.g., 32×32 cells containing centered 16×24 sprites)
Multi-tile entities (oversized sprites) - Entities that visually span multiple cells using a single larger sprite
Multi-tile entities (composite sprites) - Entities composed of multiple sprite indices, one per occupied tile

Technical Analysis

See research in conversation - key files affected:

src/UIEntity.h/cpp - Entity position and rendering
src/UIGrid.cpp:230-248 - Entity rendering loop
src/PyTexture.h/cpp - Sprite creation and sizing
src/SpatialHash.h - Entity spatial queries
src/UIEntity.cpp:37-72 - FOV computation

Implementation Priority

Entity origin offset (lowest effort, highest immediate value)
Texture display bounds (medium effort)
Multi-tile oversized sprites (higher effort)
Multi-tile composite sprites (highest effort, most flexible)

This aligns with the comment in UIEntity.h:40 mentioning plans to "allow any UIDrawable to go there, or multi-tile sprites".

## Overview This issue tracks enhancements to the entity/grid rendering system to support more flexible sprite sizing and positioning. The current system has several assumptions that limit creative flexibility: ### Current Limitations 1. **Single-cell entities**: Every entity occupies exactly one grid cell 2. **Uniform sprite sizes**: Texture sprite size = grid cell size = entity display size 3. **Fixed origin**: Sprites anchor at top-left with no offset support 4. **Point-based queries**: FOV and spatial hash treat entities as single points ### Proposed Enhancements The following sub-issues break down the work: 1. **Entity origin offset** - Allow entities to render with pixel offset from their tile position (e.g., 16×24 sprite on 16×16 grid with origin at (0,8)) 2. **Texture display bounds** - Support textures where sprite content doesn't fill the entire cell (e.g., 32×32 cells containing centered 16×24 sprites) 3. **Multi-tile entities (oversized sprites)** - Entities that visually span multiple cells using a single larger sprite 4. **Multi-tile entities (composite sprites)** - Entities composed of multiple sprite indices, one per occupied tile ### Technical Analysis See research in conversation - key files affected: - `src/UIEntity.h/cpp` - Entity position and rendering - `src/UIGrid.cpp:230-248` - Entity rendering loop - `src/PyTexture.h/cpp` - Sprite creation and sizing - `src/SpatialHash.h` - Entity spatial queries - `src/UIEntity.cpp:37-72` - FOV computation ### Implementation Priority 1. Entity origin offset (lowest effort, highest immediate value) 2. Texture display bounds (medium effort) 3. Multi-tile oversized sprites (higher effort) 4. Multi-tile composite sprites (highest effort, most flexible) This aligns with the comment in UIEntity.h:40 mentioning plans to "allow any UIDrawable to go there, or multi-tile sprites".