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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.ymlindex 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.esscenenew file mode 100644index 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 filediff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 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.cppindex 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.hppindex 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.cppindex 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.hppindex 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_; }