Entity origin offset for oversized sprites #234

New issue

Open

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

john commented

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

Owner

Summary

Allow entities to specify a pixel offset from their tile position, enabling sprites taller/wider than the grid cell size to be properly positioned.

Parent issue: #233

Use Case

A 16×24 character sprite on a 16×16 grid should render with the sprite's "feet" at the tile position, not the top of the sprite. This requires an origin offset of (0, -8) or equivalent.

Current Behavior

Entity pixel position is calculated as:

// src/UIGrid.cpp:242-244
auto pixel_pos = sf::Vector2f(
    (e->position.x*cell_width - left_spritepixels) * zoom,
    (e->position.y*cell_height - top_spritepixels) * zoom );

No offset is applied - sprite top-left aligns exactly with tile top-left.

Proposed Changes

Add to UIEntity:

sf::Vector2f render_offset;  // Pixel offset from tile position (default 0,0)

Modify grid rendering:

auto pixel_pos = sf::Vector2f(
    (e->position.x*cell_width - left_spritepixels + e->render_offset.x) * zoom,
    (e->position.y*cell_height - top_spritepixels + e->render_offset.y) * zoom );

Expose to Python:

entity.render_offset = (0, -8)  # or
entity.render_offset = mcrfpy.Vector(0, -8)

Performance Impact

Negligible - one vector addition per entity during render.

Files Affected

src/UIEntity.h - Add render_offset property
src/UIEntity.cpp - Add Python getters/setters
src/UIGrid.cpp:242-244 - Apply offset during rendering

## Summary Allow entities to specify a pixel offset from their tile position, enabling sprites taller/wider than the grid cell size to be properly positioned. **Parent issue**: #233 ## Use Case A 16×24 character sprite on a 16×16 grid should render with the sprite's "feet" at the tile position, not the top of the sprite. This requires an origin offset of (0, -8) or equivalent. ## Current Behavior Entity pixel position is calculated as: ```cpp // src/UIGrid.cpp:242-244 auto pixel_pos = sf::Vector2f( (e->position.x*cell_width - left_spritepixels) * zoom, (e->position.y*cell_height - top_spritepixels) * zoom ); ``` No offset is applied - sprite top-left aligns exactly with tile top-left. ## Proposed Changes 1. **Add to UIEntity**: ```cpp sf::Vector2f render_offset; // Pixel offset from tile position (default 0,0) ``` 2. **Modify grid rendering**: ```cpp auto pixel_pos = sf::Vector2f( (e->position.x*cell_width - left_spritepixels + e->render_offset.x) * zoom, (e->position.y*cell_height - top_spritepixels + e->render_offset.y) * zoom ); ``` 3. **Expose to Python**: ```python entity.render_offset = (0, -8) # or entity.render_offset = mcrfpy.Vector(0, -8) ``` ## Performance Impact Negligible - one vector addition per entity during render. ## Files Affected - `src/UIEntity.h` - Add render_offset property - `src/UIEntity.cpp` - Add Python getters/setters - `src/UIGrid.cpp:242-244` - Apply offset during rendering