Add composite sprite_grid for multi-tile entities, closes #237

Entities can now specify per-tile sprite indices via the sprite_grid
property. When set, each tile in a multi-tile entity renders its own
sprite from the texture atlas instead of the single entity sprite.

API:
  entity.tile_size = (3, 2)
  entity.sprite_grid = [[10, 11, 12], [20, 21, 22]]
  entity.sprite_grid = None  # revert to single sprite

Accepts nested lists, flat lists, or tuples. Use -1 for empty tiles.
Dimensions must match tile_width x tile_height.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/UIEntity.cpp

@@ -899,6 +899,105 @@ int UIEntity::set_tile_height(PyUIEntityObject* self, PyObject* value, void* clo
     return 0;
 }
 
+// #237 - Composite sprite grid
+PyObject* UIEntity::get_sprite_grid(PyUIEntityObject* self, void* closure) {
+    auto& sg = self->data->sprite_grid;
+    if (sg.empty()) {
+        Py_RETURN_NONE;
+    }
+    int tw = self->data->tile_width;
+    int th = self->data->tile_height;
+    PyObject* rows = PyList_New(th);
+    if (!rows) return NULL;
+    for (int y = 0; y < th; y++) {
+        PyObject* row = PyList_New(tw);
+        if (!row) { Py_DECREF(rows); return NULL; }
+        for (int x = 0; x < tw; x++) {
+            int idx = sg[y * tw + x];
+            PyList_SET_ITEM(row, x, PyLong_FromLong(idx));
+        }
+        PyList_SET_ITEM(rows, y, row);
+    }
+    return rows;
+}
+
+int UIEntity::set_sprite_grid(PyUIEntityObject* self, PyObject* value, void* closure) {
+    if (value == Py_None) {
+        self->data->sprite_grid.clear();
+        if (self->data->grid) self->data->grid->markDirty();
+        return 0;
+    }
+
+    int tw = self->data->tile_width;
+    int th = self->data->tile_height;
+
+    // Accept flat list or nested list
+    if (!PyList_Check(value) && !PyTuple_Check(value)) {
+        PyErr_SetString(PyExc_TypeError, "sprite_grid must be a list of lists, a flat list, or None");
+        return -1;
+    }
+
+    Py_ssize_t outer_len = PySequence_Size(value);
+    if (outer_len < 0) return -1;
+
+    std::vector<int> new_grid;
+
+    // Check if it's nested (first element is a sequence)
+    PyObject* first = (outer_len > 0) ? PySequence_GetItem(value, 0) : nullptr;
+    bool nested = first && (PyList_Check(first) || PyTuple_Check(first));
+    Py_XDECREF(first);
+
+    if (nested) {
+        if (outer_len != th) {
+            PyErr_Format(PyExc_ValueError,
+                "sprite_grid has %zd rows, expected %d (tile_height)", outer_len, th);
+            return -1;
+        }
+        new_grid.reserve(tw * th);
+        for (int y = 0; y < th; y++) {
+            PyObject* row = PySequence_GetItem(value, y);
+            if (!row) return -1;
+            Py_ssize_t row_len = PySequence_Size(row);
+            if (row_len != tw) {
+                Py_DECREF(row);
+                PyErr_Format(PyExc_ValueError,
+                    "sprite_grid row %d has %zd items, expected %d (tile_width)", y, row_len, tw);
+                return -1;
+            }
+            for (int x = 0; x < tw; x++) {
+                PyObject* item = PySequence_GetItem(row, x);
+                if (!item) { Py_DECREF(row); return -1; }
+                long idx = PyLong_AsLong(item);
+                Py_DECREF(item);
+                if (idx == -1 && PyErr_Occurred()) { Py_DECREF(row); return -1; }
+                new_grid.push_back(static_cast<int>(idx));
+            }
+            Py_DECREF(row);
+        }
+    } else {
+        // Flat list
+        if (outer_len != tw * th) {
+            PyErr_Format(PyExc_ValueError,
+                "sprite_grid has %zd items, expected %d (tile_width * tile_height)",
+                outer_len, tw * th);
+            return -1;
+        }
+        new_grid.reserve(tw * th);
+        for (Py_ssize_t i = 0; i < outer_len; i++) {
+            PyObject* item = PySequence_GetItem(value, i);
+            if (!item) return -1;
+            long idx = PyLong_AsLong(item);
+            Py_DECREF(item);
+            if (idx == -1 && PyErr_Occurred()) return -1;
+            new_grid.push_back(static_cast<int>(idx));
+        }
+    }
+
+    self->data->sprite_grid = std::move(new_grid);
+    if (self->data->grid) self->data->grid->markDirty();
+    return 0;
+}
+
 PyObject* UIEntity::die(PyUIEntityObject* self, PyObject* Py_UNUSED(ignored))
 {
     // Check if entity has a grid
@@ -1657,6 +1756,11 @@ PyGetSetDef UIEntity::getsetters[] = {
      "Entity width in tiles (int). Must be >= 1. Default 1.", NULL},
     {"tile_height", (getter)UIEntity::get_tile_height, (setter)UIEntity::set_tile_height,
      "Entity height in tiles (int). Must be >= 1. Default 1.", NULL},
+    // #237 - Composite sprite grid
+    {"sprite_grid", (getter)UIEntity::get_sprite_grid, (setter)UIEntity::set_sprite_grid,
+     "Per-tile sprite indices for composite multi-tile entities (list of lists or None). "
+     "Row-major, dimensions must match tile_width x tile_height. Use -1 for empty tiles. "
+     "When set, each tile renders its own sprite index instead of the single entity sprite.", NULL},
     // #296 - Label system
     {"labels", (getter)UIEntity::get_labels, (setter)UIEntity::set_labels,
      "Set of string labels for collision/targeting (frozenset). "

src/UIEntity.h

@@ -73,6 +73,7 @@ public:
     sf::Vector2f sprite_offset; // pixel offset for oversized sprites (applied pre-zoom)
     int tile_width = 1;  // #236: entity size in tiles (for multi-tile entities)
     int tile_height = 1;
+    std::vector<int> sprite_grid; // #237: per-tile sprite indices (row-major, -1 = empty)
     std::unordered_set<std::string> labels; // #296: entity label system for collision/targeting
     PyObject* step_callback = nullptr; // #299: callback for grid.step() turn management
     int default_behavior = 0; // #299: BehaviorType::IDLE - behavior to revert to after DONE
@@ -178,6 +179,9 @@ public:
     static int set_tile_width(PyUIEntityObject* self, PyObject* value, void* closure);
     static PyObject* get_tile_height(PyUIEntityObject* self, void* closure);
     static int set_tile_height(PyUIEntityObject* self, PyObject* value, void* closure);
+    // #237 - Composite sprite grid
+    static PyObject* get_sprite_grid(PyUIEntityObject* self, void* closure);
+    static int set_sprite_grid(PyUIEntityObject* self, PyObject* value, void* closure);
 
     // #295 - cell_pos (integer logical position)
     static PyObject* get_cell_pos(PyUIEntityObject* self, void* closure);
@@ -247,7 +251,8 @@ namespace mcrfpydef {
                             "    name (str): Element name for finding. Default: None\n"
                             "    x (float): X grid position override (tile coords). Default: 0\n"
                             "    y (float): Y grid position override (tile coords). Default: 0\n"
-                            "    sprite_offset (tuple): Pixel offset for oversized sprites. Default: (0, 0)\n\n"
+                            "    sprite_offset (tuple): Pixel offset for oversized sprites. Default: (0, 0)\n"
+                            "    sprite_grid (list): Per-tile sprite indices for composite entities. Default: None\n\n"
                             "Attributes:\n"
                             "    pos (Vector): Pixel position relative to grid (requires grid attachment)\n"
                             "    x, y (float): Pixel position components (requires grid attachment)\n"

src/UIGrid.cpp

@@ -207,14 +207,30 @@ void UIGrid::render(sf::Vector2f offset, sf::RenderTarget& target)
                 continue; // Skip this entity as it's not visible
             }
 
-            //auto drawent = e->cGrid->indexsprite.drawable();
-            auto& drawent = e->sprite;
-            //drawent.setScale(zoom, zoom);
-            drawent.setScale(sf::Vector2f(zoom, zoom));
             auto pixel_pos = sf::Vector2f(
                 (e->position.x*cell_width - left_spritepixels + e->sprite_offset.x) * zoom,
                 (e->position.y*cell_height - top_spritepixels + e->sprite_offset.y) * zoom );
-            drawent.render(pixel_pos, *activeTexture);
+
+            // #237: Composite sprite grid - render per-tile sprites
+            if (!e->sprite_grid.empty() && e->sprite.getTexture()) {
+                auto tex = e->sprite.getTexture();
+                for (int dy = 0; dy < e->tile_height; dy++) {
+                    for (int dx = 0; dx < e->tile_width; dx++) {
+                        int idx = e->sprite_grid[dy * e->tile_width + dx];
+                        if (idx < 0) continue;
+                        auto tile_pos = sf::Vector2f(
+                            pixel_pos.x + dx * cell_width * zoom,
+                            pixel_pos.y + dy * cell_height * zoom);
+                        auto spr = tex->sprite(idx, tile_pos, sf::Vector2f(zoom, zoom));
+                        activeTexture->draw(spr);
+                    }
+                }
+            } else {
+                // Single sprite path
+                auto& drawent = e->sprite;
+                drawent.setScale(sf::Vector2f(zoom, zoom));
+                drawent.render(pixel_pos, *activeTexture);
+            }
 
             entitiesRendered++;
         }