From 89d68d766834eb18611db8a452d9a9c0271733f6 Mon Sep 17 00:00:00 2001
From: Axel Meyer <axel.meyer@durania.net>
Date: Mon, 1 Jun 2026 21:50:56 +0200
Subject: [PATCH] feat(maps): set_cell_material / get_cell_material public APIs

Mirrors the existing set_vertex / get_vertex pattern. Bounds and
unknown-layer guards raise the same shape of error as the v3
write-API family. Lazy-allocates layer.cells_material on first
write so maps that never use cell-tile painting stay byte-clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 init.lua | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/init.lua b/init.lua
index f99b65f..bccc5f7 100644
--- a/init.lua
+++ b/init.lua
@@ -1583,6 +1583,42 @@ function M.get_vertex(layer_name, vx, vy, map_id)
     return v == 1 or v == true
 end
 
+-- 0.5.7: set/clear the per-cell material flag at (cx, cy) on the named
+-- layer. painted: bool. Lazy-allocates layer.cells_material on first
+-- write. Out-of-bounds raises a bounds error. Unknown layer raises a
+-- layer-not-found error.
+function M.set_cell_material(layer_name, cx, cy, painted, map_id)
+    local m = require_map(map_id)
+    local layer = m.layers[layer_name]
+    if not layer then
+        error(string.format("maps.set_cell_material: no layer '%s'", layer_name))
+    end
+    local w, h = m.size.w, m.size.h
+    if cx < 0 or cx >= w or cy < 0 or cy >= h then
+        error(string.format("maps.set_cell_material: out of bounds (%d, %d) for %dx%d map",
+            cx, cy, w, h))
+    end
+    local cm = ensure_cells_material(layer, w, h)
+    cm[cy * w + cx + 1] = painted and 1 or 0
+end
+
+-- 0.5.7: read the per-cell material flag. Returns false if
+-- layer.cells_material is absent or the entry is unset. Does NOT
+-- include vertex-derived material — call cell_material_slot or render
+-- if you need the effective state.
+function M.get_cell_material(layer_name, cx, cy, map_id)
+    local m = require_map(map_id)
+    local layer = m.layers[layer_name]
+    if not layer then
+        error(string.format("maps.get_cell_material: no layer '%s'", layer_name))
+    end
+    local w, h = m.size.w, m.size.h
+    if cx < 0 or cx >= w or cy < 0 or cy >= h then return false end
+    if layer.cells_material == nil then return false end
+    local v = layer.cells_material[cy * w + cx + 1]
+    return v ~= nil and v ~= 0 and v ~= false
+end
+
 function M.set_roof(x, y, value, map_id)
     local map = require_map(map_id)
     if x < 0 or y < 0 or x >= map.size.w or y >= map.size.h then