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(engine): register tilemap data before renderer initialization

yhhea148b3ebaf1
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index d4e91213d..452d9a95b 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -24,7 +24,7 @@ permissions:
# but-never-run (the hand-kept lists had drifted).
env:
CPP_TESTS: >-
- test_ecs test_events test_particle test_tilemap test_sparse_set
+ test_ecs test_events test_particle test_tilemap test_tilemap_context test_sparse_set
test_resource_pool test_shader_variant test_log_format test_registry_safety
test_registry_ondestroy test_view_api_matrix
test_hierarchy_links test_entity_activity test_transform_traversal test_tween_activity
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8b71f6691..ac773b7ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Tilemap data is available before renderer initialization.** Headless tile reads, edits and chunk serialization use the context's own data service without requiring graphics setup. Initializing the renderer keeps any preloaded maps; shutdown and reinitialization create a fresh service.
+
- **Tilemap bucket fills finish every discovered cell within the safety limit.** A 16,384-cell region fills completely without a false warning, while larger or infinite regions remain bounded. Traversal uses a FIFO cursor and reads each boundary cell once. Flip flags participate in the brush comparison, and unchanged cells are omitted from the paint transaction.
- **Switching tilemap layers clears the previous palette before drawing.** Palette loads restart when the project changes even if entity IDs are reused. Superseded reads stop requesting subsequent tilesets or atlas dimensions after a layer switch or panel close.
diff --git a/sdk/tests/tilemap-context-wasm.test.ts b/sdk/tests/tilemap-context-wasm.test.ts
new file mode 100644
index 000000000..88f7c8e3b
--- /dev/null
+++ b/sdk/tests/tilemap-context-wasm.test.ts
@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { ESEngineModule } from '../src/wasm';
+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
+
+describe.skipIf(!HAS_WASM)('headless tilemap context bindings', () => {
+ let engine: ESEngineModule;
+ beforeAll(async () => {
+ engine = await loadWasmModule();
+ expect(typeof engine.tilemap_initLayer).toBe('function');
+ });
+
+ it('reads, exports and imports tile data without initializing a renderer', () => {
+ engine.setActiveContext(null);
+ engine.tilemap_initLayer!(10, 8, 8, 16, 16);
+ engine.tilemap_initLayer!(11, 8, 8, 16, 16);
+ try {
+ engine.tilemap_setTile!(10, 2, 3, 7);
+ expect(engine.tilemap_getTile!(10, 2, 3)).toBe(7);
+ const blob = engine.tilemap_exportChunks!(10);
+ expect(blob.length).toBeGreaterThan(0);
+ expect(engine.tilemap_importChunks!(11, blob)).toBe(true);
+ expect(engine.tilemap_getTile!(11, 2, 3)).toBe(7);
+ } finally {
+ engine.tilemap_destroyLayer!(10);
+ engine.tilemap_destroyLayer!(11);
+ }
+ });
+
+ it('keeps identical layer handles isolated between headless engine contexts', () => {
+ const first = new engine.EstellaContext();
+ const second = new engine.EstellaContext();
+ try {
+ engine.setActiveContext(first);
+ engine.tilemap_initLayer!(10, 8, 8, 16, 16);
+ engine.tilemap_setTile!(10, 2, 3, 7);
+ engine.setActiveContext(second);
+ engine.tilemap_initLayer!(10, 8, 8, 16, 16);
+ engine.tilemap_setTile!(10, 2, 3, 9);
+ expect(engine.tilemap_getTile!(10, 2, 3)).toBe(9);
+ engine.setActiveContext(first);
+ expect(engine.tilemap_getTile!(10, 2, 3)).toBe(7);
+ } finally {
+ engine.setActiveContext(null);
+ first.delete();
+ second.delete();
+ }
+ });
+});
diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cpp
index 3d754d279..37a1439e2 100644
--- a/src/esengine/core/EstellaContext.cpp
+++ b/src/esengine/core/EstellaContext.cpp
@@ -50,11 +50,6 @@
namespace esengine {
-#ifdef ES_ENABLE_TILEMAP
-// Forward declaration — defined in TilemapBindings.cpp for web builds,
-// needs local instance for non-web. For now we create a fresh system.
-#endif
-
EstellaContext::EstellaContext() {
// Logic systems must exist even for headless apps that never call init()
// (e.g. tooling / tests that drive UI layout without a GL context). Without
@@ -72,6 +67,11 @@ void EstellaContext::registerLogicSystems() {
services_.registerOwned<ecs::TransformSystem>(makeUnique<ecs::TransformSystem>());
services_.registerOwned<ecs::UISystem>(makeUnique<ecs::UISystem>());
services_.registerOwned<animation::TweenSystem>(makeUnique<animation::TweenSystem>());
+#ifdef ES_ENABLE_TILEMAP
+ // Chunk data and tile queries do not need a renderer. Register here once so
+ // later renderer initialization also retains maps loaded by headless tooling.
+ services_.registerOwned<tilemap::TilemapSystem>(makeUnique<tilemap::TilemapSystem>());
+#endif
}
EstellaContext::~EstellaContext() {
@@ -151,7 +151,7 @@ void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {
// GPU state is owned by the device: pipelines (setPipeline) carry program/blend/depth/
// stencil/cull, so there is no separate per-App state tracker to wire up here.
- // GPU-independent logic systems (Transform/UI/Tween) are registered here too
+ // GPU-independent logic systems (Transform/UI/Tween/Tilemap) are registered here too
// for the shutdown()+init() re-init path; the constructor already registered
// them for the headless/first-use path. Idempotent, so this is a no-op when
// they are already present.
@@ -178,10 +178,6 @@ void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {
services_.registerOwned<GeometryManager>(makeUnique<GeometryManager>());
-#ifdef ES_ENABLE_TILEMAP
- services_.registerOwned<tilemap::TilemapSystem>(makeUnique<tilemap::TilemapSystem>());
-#endif
-
auto renderFrame = makeUnique<RenderFrame>(*gfxDevicePtr, *rc, *rm);
renderFrame->setPresentedOverlayDraw(immediateDrawPtr);
renderFrame->addPlugin(std::make_unique<SpritePlugin>());
diff --git a/src/esengine/core/EstellaContext.hpp b/src/esengine/core/EstellaContext.hpp
index 75f229b4a..94f490405 100644
--- a/src/esengine/core/EstellaContext.hpp
+++ b/src/esengine/core/EstellaContext.hpp
@@ -73,7 +73,7 @@ public:
private:
void initSubsystems(Unique<GfxDevice> gfxDevice);
/**
- * Register the GPU-independent ECS logic systems (Transform/UI/Tween).
+ * Register the GPU-independent logic systems (Transform/UI/Tween/Tilemap).
* Called from the constructor *and* initSubsystems so they exist even for
* headless apps that never call init() — otherwise require<UISystem>() etc.
* return a null reference (silent wasm address-0 corruption). Idempotent.
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index f2889b766..da1fa5359 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -91,6 +91,13 @@ add_executable(test_tilemap
target_link_libraries(test_tilemap PRIVATE esengine)
add_test(NAME test_tilemap COMMAND test_tilemap)
+add_executable(test_tilemap_context
+ tilemap/test_tilemap_context.cpp
+ ${CMAKE_SOURCE_DIR}/src/esengine/renderer/rhi/GfxDevice.cpp
+)
+target_link_libraries(test_tilemap_context PRIVATE esengine)
+add_test(NAME test_tilemap_context COMMAND test_tilemap_context)
+
# AOT: compiled TypeScript against a real Registry. The .c is generated by
# @estella/compiler and checked in (compiler/tests/generated.test.ts keeps it
# fresh); this harness is what holds the generated OFFSETS against the C++
diff --git a/tests/tilemap/test_tilemap_context.cpp b/tests/tilemap/test_tilemap_context.cpp
new file mode 100644
index 000000000..53130a355
--- /dev/null
+++ b/tests/tilemap/test_tilemap_context.cpp
@@ -0,0 +1,44 @@
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include <doctest.h>
+
+#include <esengine/core/EstellaContext.hpp>
+#include <esengine/tilemap/TilemapSystem.hpp>
+#include "../renderer/MockGfxDevice.hpp"
+
+using namespace esengine;
+using esengine::tilemap::TilemapSystem;
+
+TEST_CASE("headless contexts own independent tilemap data") {
+ EstellaContext first;
+ EstellaContext second;
+ auto* a = first.tryGet<TilemapSystem>();
+ auto* b = second.tryGet<TilemapSystem>();
+ REQUIRE(a != nullptr);
+ REQUIRE(b != nullptr);
+ CHECK(a != b);
+ const auto layer = Entity::make(10, 1);
+ a->initInfiniteLayer(layer, 16, 16);
+ b->initInfiniteLayer(layer, 16, 16);
+ a->setTile(layer, -33, 64, 7);
+ b->setTile(layer, -33, 64, 9);
+ CHECK(a->getTile(layer, -33, 64) == 7);
+ CHECK(b->getTile(layer, -33, 64) == 9);
+ CHECK_FALSE(first.isInitialized());
+ CHECK_FALSE(second.isInitialized());
+}
+
+TEST_CASE("renderer initialization retains tilemaps prepared headlessly") {
+ EstellaContext context;
+ auto* tiles = context.tryGet<TilemapSystem>();
+ REQUIRE(tiles != nullptr);
+ const auto layer = Entity::make(10, 1);
+ tiles->initLayer(layer, 8, 8, 16, 16);
+ tiles->setTile(layer, 2, 3, 11);
+ REQUIRE(context.init(makeUnique<MockGfxDevice>()));
+ CHECK(context.tryGet<TilemapSystem>() == tiles);
+ CHECK(context.require<TilemapSystem>().getTile(layer, 2, 3) == 11);
+ context.shutdown();
+ REQUIRE(context.init(makeUnique<MockGfxDevice>()));
+ CHECK(context.tryGet<TilemapSystem>() != nullptr);
+ CHECK_FALSE(context.require<TilemapSystem>().hasLayer(layer));
+}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 4a45cd324..d6067f3e3 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(engine): register tilemap data before renderer initialization':
+ { note: 'Tilemap data is available before renderer initialization.' },
'fix(tilemap): complete bounded fills and avoid repeated boundary reads':
{ note: 'Tilemap bucket fills finish every discovered cell within the safety limit.' },
'fix(editor): sync bounded tilemap fill corrections':