Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(render): tilemap chunk cache keeps only invariants — origin, parallax and tint apply per frame

esengine416a710258ab
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index fbee65d1b..0d206178b 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -245,6 +245,16 @@ jobs:
ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-gidobj.textures.json \
ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 \
'ESTELLA_VERIFY_EXPECT=[{"x":0.5,"y":0.5,"rgb":[0,255,0],"tol":40},{"x":0.5,"y":0.12,"rgb":[0,0,0],"tol":30}]'
+ # Parallax on a cached-chunk tilemap: the camera moves while the layer
+ # model is untouched, so only the per-frame origin/parallax merge (not a
+ # revision-bump rebuild) can place the tiles — guards against baking
+ # camera-dependent offsets into the chunk cache.
+ run_scene tilemap-parallax \
+ ESTELLA_VERIFY_SCENE=/scenes/tilemap-parallax.esscene \
+ ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-flip.textures.json \
+ ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 \
+ 'ESTELLA_VERIFY_MOVE={"component":"Camera","to":[48,-16],"steps":3}' \
+ 'ESTELLA_VERIFY_EXPECT=[{"x":0.30,"y":0.40,"rgb":[255,0,0]},{"x":0.10,"y":0.40,"rgb":[0,0,0],"tol":20},{"x":0.50,"y":0.40,"rgb":[0,255,0]}]'
run_scene ui-mask \
ESTELLA_VERIFY_SCENE=/scenes/ui-list-mask.esscene \
ESTELLA_VERIFY_MANIFEST=/scenes/ui-list-mask.textures.json \
diff --git a/desktop/public/scenes/tilemap-parallax.esscene b/desktop/public/scenes/tilemap-parallax.esscene
new file mode 100644
index 000000000..ae00cba9e
--- /dev/null
+++ b/desktop/public/scenes/tilemap-parallax.esscene
@@ -0,0 +1,71 @@
+{
+ "version": "1.0",
+ "name": "TilemapParallax",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 16,
+ "y": -16,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 40,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Tilemap",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "TilemapLayer",
+ "data": {
+ "cellSize": {
+ "x": 16,
+ "y": 16
+ },
+ "tileset": "@uuid:aaaaaaaa-1111-2222-3333-444444444444",
+ "tilesetColumns": 2,
+ "tilesetRows": 2,
+ "visible": true,
+ "chunks": "RVNUTQEAAAAAAAAAAAAAAAEAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAwAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+ "parallaxFactor": {
+ "x": 0.5,
+ "y": 1.0
+ }
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
\ No newline at end of file
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index c2f7d9f71..1e91b1d6b 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -145,6 +145,30 @@ app.whenReady().then(async () => {
// carrying a TrailRenderer along a world-space path, one frame per sample, so
// the trail system records points — motion a static scene can't express.
// Requires play mode (ESTELLA_VERIFY_PLAY=1) for the trail update to run.
+ // ESTELLA_VERIFY_MOVE = {"component":"TilemapLayer","to":[x,y],"steps":N}:
+ // after the scene settles, teleport the first entity carrying the named
+ // component to a world position and step N frames — proves render paths
+ // that cache geometry still track a moving entity (e.g. tilemap origin).
+ if (process.env.ESTELLA_VERIFY_MOVE) {
+ const move = JSON.parse(process.env.ESTELLA_VERIFY_MOVE);
+ await exec(`(async () => {
+ const cfg = ${JSON.stringify(move)};
+ const api = window.__estellaHeadless.api;
+ const flat = [];
+ const walk = (nodes) => { for (const n of nodes) { flat.push(n.id); if (n.children) walk(n.children); } };
+ walk(api.getSceneTree());
+ const want = cfg.component.replace(/\\s+/g, '');
+ let target = null;
+ for (const id of flat) {
+ const e = api.getEntity(id);
+ if (e && e.components && e.components.some((c) => c.replace(/\\s+/g, '') === want)) { target = id; break; }
+ }
+ if (target == null) throw new Error('no ' + cfg.component + ' entity in scene');
+ await api.step(2, 1 / 60);
+ api.setEntityXY(target, cfg.to[0], cfg.to[1]);
+ await api.step(cfg.steps ?? 2, 1 / 60);
+ })()`);
+ }
if (process.env.ESTELLA_VERIFY_TRAIL) {
const trail = JSON.parse(process.env.ESTELLA_VERIFY_TRAIL);
await exec(`(async () => {
diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
index d6584a687..97e2c4bf1 100644
--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
@@ -20,7 +20,6 @@ void TilemapRenderPlugin::init(RenderFrameContext& ctx) {
void TilemapRenderPlugin::rebuildChunk(
const tilemap::TilemapSystem::LayerData& layer,
const tilemap::ChunkData& chunk, tilemap::ChunkCoord coord,
- f32 originX, f32 originY, u32 packedColor,
const std::vector<tilemap::TilesetSlot>& slots,
const std::vector<ResolvedSlot>& resolved,
Entity entity, ChunkCache& cache
@@ -74,8 +73,8 @@ void TilemapRenderPlugin::rebuildChunk(
f32 worldX, worldY;
if (layer.grid_type == tilemap::GridType::Isometric) {
- worldX = originX + static_cast<f32>(tx - ty) * hw;
- worldY = originY - static_cast<f32>(tx + ty) * hh;
+ worldX = static_cast<f32>(tx - ty) * hw;
+ worldY = -static_cast<f32>(tx + ty) * hh;
} else if (layer.grid_type == tilemap::GridType::StaggeredIsometric
|| layer.grid_type == tilemap::GridType::Hexagonal) {
// Staggered/hex share one layout: the stagger axis advances by
@@ -90,19 +89,19 @@ void TilemapRenderPlugin::rebuildChunk(
if (layer.hex_stagger_axis_x) {
f32 colW = (layer.tile_width + side) * 0.5f;
bool staggered = ((tx & 1) != 0) != layer.hex_stagger_index_even;
- worldX = originX + static_cast<f32>(tx) * colW + hw;
- worldY = originY - static_cast<f32>(ty) * layer.tile_height
+ worldX = static_cast<f32>(tx) * colW + hw;
+ worldY = -static_cast<f32>(ty) * layer.tile_height
- (staggered ? hh : 0.0f) - hh;
} else {
f32 rowH = (layer.tile_height + side) * 0.5f;
bool staggered = ((ty & 1) != 0) != layer.hex_stagger_index_even;
- worldX = originX + static_cast<f32>(tx) * layer.tile_width
+ worldX = static_cast<f32>(tx) * layer.tile_width
+ (staggered ? hw : 0.0f) + hw;
- worldY = originY - static_cast<f32>(ty) * rowH - hh;
+ worldY = -static_cast<f32>(ty) * rowH - hh;
}
} else {
- worldX = originX + static_cast<f32>(tx) * layer.tile_width + hw;
- worldY = originY - static_cast<f32>(ty) * layer.tile_height - hh;
+ worldX = static_cast<f32>(tx) * layer.tile_width + hw;
+ worldY = -static_cast<f32>(ty) * layer.tile_height - hh;
}
// Base tile UV rect (GL v increases upward, so vBottom < vTop),
@@ -128,10 +127,10 @@ void TilemapRenderPlugin::rebuildChunk(
SlotMesh& mesh = cache.slots[slotIndex];
u32 baseVertex = static_cast<u32>(mesh.vertices.size());
- mesh.vertices.push_back({ {worldX - hw, worldY - hh}, packedColor, {bl.x, bl.y} });
- mesh.vertices.push_back({ {worldX + hw, worldY - hh}, packedColor, {br.x, br.y} });
- mesh.vertices.push_back({ {worldX + hw, worldY + hh}, packedColor, {tr.x, tr.y} });
- mesh.vertices.push_back({ {worldX - hw, worldY + hh}, packedColor, {tl.x, tl.y} });
+ mesh.vertices.push_back({ {worldX - hw, worldY - hh}, 0, {bl.x, bl.y} });
+ mesh.vertices.push_back({ {worldX + hw, worldY - hh}, 0, {br.x, br.y} });
+ mesh.vertices.push_back({ {worldX + hw, worldY + hh}, 0, {tr.x, tr.y} });
+ mesh.vertices.push_back({ {worldX - hw, worldY + hh}, 0, {tl.x, tl.y} });
for (u32 i = 0; i < 6; ++i) {
mesh.indices.push_back(baseVertex + BATCH_QUAD_INDICES[i]);
@@ -276,7 +275,6 @@ void TilemapRenderPlugin::collect(RenderCollectContext& collect_ctx) {
|| (cache.has_animated_tiles && layer.anim_revision != cache.built_anim_revision)
|| cache.slots.size() != slots.size()) {
rebuildChunk(layer, chunkData, coord,
- adjOriginX, adjOriginY, packedColor,
slots, resolved, entity, cache);
cache.built_revision = chunkData.revision;
cache.built_anim_revision = layer.anim_revision;
@@ -286,8 +284,11 @@ void TilemapRenderPlugin::collect(RenderCollectContext& collect_ctx) {
const SlotMesh& mesh = cache.slots[si];
if (mesh.indices.empty()) continue;
u32 baseVertex = static_cast<u32>(slotVertices[si].size());
- slotVertices[si].insert(slotVertices[si].end(),
- mesh.vertices.begin(), mesh.vertices.end());
+ for (const BatchVertex& v : mesh.vertices) {
+ slotVertices[si].push_back({
+ { v.position.x + adjOriginX, v.position.y + adjOriginY },
+ packedColor, v.texCoord });
+ }
for (u32 idx : mesh.indices) {
slotIndices[si].push_back(baseVertex + idx);
}
diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
index 2cd6297ac..a1e25e8b7 100644
--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
@@ -26,6 +26,9 @@ public:
private:
// Per-tileset-slot geometry for one chunk. A multi-tileset layer splits a
// chunk's tiles across slots (one texture each) so each becomes its own batch.
+ // Vertices are layer-local and untinted: origin, parallax offset and tint are
+ // applied when merging into the frame's batch, so moving, tinting or
+ // parallax-scrolling a layer never invalidates the cache.
struct SlotMesh {
std::vector<BatchVertex> vertices;
std::vector<u32> indices;
@@ -61,7 +64,6 @@ private:
void rebuildChunk(const tilemap::TilemapSystem::LayerData& layer,
const tilemap::ChunkData& chunk, tilemap::ChunkCoord coord,
- f32 originX, f32 originY, u32 packedColor,
const std::vector<tilemap::TilesetSlot>& slots,
const std::vector<ResolvedSlot>& resolved,
Entity entity, ChunkCache& cache);
diff --git a/src/esengine/tilemap/TilemapSystem.cpp b/src/esengine/tilemap/TilemapSystem.cpp
index 21b2ce53b..5e8420804 100644
--- a/src/esengine/tilemap/TilemapSystem.cpp
+++ b/src/esengine/tilemap/TilemapSystem.cpp
@@ -96,14 +96,6 @@ void buildChunksFromFlat(TilemapSystem::LayerData& layer,
} // namespace
-void TilemapSystem::markAllChunksDirty(Entity entity) {
- auto* layer = getLayerDataMut(entity);
- if (!layer) return;
- for (auto& [coord, chunk] : layer->chunks) {
- chunk.revision = ++layer->edit_revision;
- }
-}
-
void TilemapSystem::initLayer(Entity entity, u32 width, u32 height,
f32 tileWidth, f32 tileHeight) {
LayerData layer;
diff --git a/src/esengine/tilemap/TilemapSystem.hpp b/src/esengine/tilemap/TilemapSystem.hpp
index 3ab7bbfed..8703a3d47 100644
--- a/src/esengine/tilemap/TilemapSystem.hpp
+++ b/src/esengine/tilemap/TilemapSystem.hpp
@@ -175,8 +175,6 @@ public:
void worldToTile(Entity entity, f32 wx, f32 wy,
f32 originX, f32 originY, i32& outTx, i32& outTy) const;
- void markAllChunksDirty(Entity entity);
-
using LayerMap = std::unordered_map<Entity, LayerData>;
const LayerMap& allLayers() const { return layers_; }