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.

feat(editor): model-authoritative tile painting command (REARCH_TILEMAP T3a)

esengine225b25cf5132
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 8a2376de7..045912616 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -1,6 +1,7 @@
// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { SceneData, PrefabData, ProcessedEntity } from 'esengine';
+import { TilemapAPI } from 'esengine';
import type { EntityId, InspectorFieldType, InspectorFieldValue } from '@/types';
import { EditorHistory, EditorHistoryImpl } from './EditorHistory';
import { SceneModel, SceneModelImpl } from './SceneModel';
@@ -17,6 +18,13 @@ import {
type SceneEntity = SceneData['entities'][number];
type SceneComponent = SceneEntity['components'][number];
+/** A single tile edit: set the tile at grid (x, y) to `tileId` (0 = erase). */
+export interface TilePaint {
+ x: number;
+ y: number;
+ tileId: number;
+}
+
// — Model-authoritative commands (REARCH_EDITOR_MODEL.md) —
//
// Every mutation edits the SceneModel ONLY (the session's source of truth). The
@@ -432,6 +440,37 @@ export class SceneCommandsImpl {
}
this.endGesture();
}
+
+ /**
+ * Paint tiles into a TilemapLayer entity — model-authoritative (REARCH_TILEMAP T3).
+ *
+ * Tile data is a C++-side chunk store the scene carries as the TilemapLayer's
+ * out-of-band `chunks` blob. We apply the edits live to the C++ tilemap (so the
+ * viewport updates immediately) and then commit the fresh blob into the model — the
+ * editor's source of truth, so a save (model serialize) and a play→stop rebuild
+ * (loadSceneData → codec re-imports the blob) both reproduce exactly what was painted.
+ * One undo step; its closures RE-RESOLVE the runtime entity (it changes across a
+ * play→stop rebuild) and re-import the snapshotted before/after blob.
+ */
+ paintTiles(sourceId: EntityId, edits: TilePaint[]): void {
+ if (edits.length === 0) return;
+ const rt = this.model.runtimeFor(sourceId);
+ if (rt === undefined) return;
+
+ const before = TilemapAPI.exportChunks(rt);
+ for (const e of edits) TilemapAPI.setTile(rt, e.x, e.y, e.tileId);
+ const after = TilemapAPI.exportChunks(rt);
+ if (after === before) return; // painted the same ids that were already there
+
+ this.model.setField(sourceId, 'TilemapLayer', 'chunks', after);
+
+ const restore = (blob: string) => {
+ const r = this.model.runtimeFor(sourceId);
+ if (r !== undefined) TilemapAPI.importChunks(r, blob);
+ this.model.setField(sourceId, 'TilemapLayer', 'chunks', blob);
+ };
+ this.history.record('Paint Tiles', () => restore(after), () => restore(before));
+ }
}
/** The app's default-session commands. Other sessions construct their own SceneCommandsImpl(model, history). */
diff --git a/desktop/tests/paint-tiles.test.ts b/desktop/tests/paint-tiles.test.ts
new file mode 100644
index 000000000..b50cd1c75
--- /dev/null
+++ b/desktop/tests/paint-tiles.test.ts
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file SceneCommands.paintTiles (REARCH_TILEMAP T3a) — model-authoritative tile
+ * painting: edits apply live to the C++ tilemap AND commit the chunk blob into
+ * the model, so undo/redo restore both. TilemapAPI is spied (the C++ chunk store
+ * needs an initialized GL layer, out of scope for a node unit test); the model +
+ * undo plumbing is real.
+ */
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { TilemapAPI } from 'esengine';
+import type { SceneData } from 'esengine';
+import { SceneModelImpl } from '@/engine/SceneModel';
+import { EditorHistoryImpl } from '@/engine/EditorHistory';
+import { SceneCommandsImpl } from '@/engine/SceneCommands';
+
+function tilemapScene(): SceneData {
+ return {
+ version: '1.0',
+ name: 't',
+ entities: [
+ {
+ id: 1,
+ name: 'Map',
+ parent: null,
+ children: [],
+ components: [
+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 }, scale: { x: 1, y: 1, z: 1 } } },
+ { type: 'TilemapLayer', data: { cellSize: { x: 16, y: 16 }, tileset: 0 } },
+ ],
+ },
+ ],
+ } as unknown as SceneData;
+}
+
+const chunksOf = (model: SceneModelImpl): unknown =>
+ (model.entityBySource(1)!.components.find((c) => c.type === 'TilemapLayer')!.data as Record<string, unknown>).chunks;
+
+describe('SceneCommands.paintTiles', () => {
+ let model: SceneModelImpl;
+ let history: EditorHistoryImpl;
+ let cmds: SceneCommandsImpl;
+
+ beforeEach(() => {
+ model = new SceneModelImpl();
+ history = new EditorHistoryImpl();
+ cmds = new SceneCommandsImpl(model, history);
+ model.adopt(tilemapScene(), new Map([[1, 100]])); // source 1 → runtime 100
+ });
+ afterEach(() => vi.restoreAllMocks());
+
+ it('applies edits live to C++ and commits the chunk blob to the model, undoably', () => {
+ const setTile = vi.spyOn(TilemapAPI, 'setTile').mockImplementation(() => {});
+ const importChunks = vi.spyOn(TilemapAPI, 'importChunks').mockReturnValue(true);
+ vi.spyOn(TilemapAPI, 'exportChunks').mockReturnValueOnce('BEFORE').mockReturnValueOnce('AFTER');
+
+ cmds.paintTiles(1, [{ x: 2, y: 3, tileId: 5 }, { x: 2, y: 4, tileId: 5 }]);
+
+ expect(setTile).toHaveBeenNthCalledWith(1, 100, 2, 3, 5);
+ expect(setTile).toHaveBeenNthCalledWith(2, 100, 2, 4, 5);
+ expect(chunksOf(model)).toBe('AFTER');
+
+ history.undo();
+ expect(importChunks).toHaveBeenLastCalledWith(100, 'BEFORE');
+ expect(chunksOf(model)).toBe('BEFORE');
+
+ history.redo();
+ expect(importChunks).toHaveBeenLastCalledWith(100, 'AFTER');
+ expect(chunksOf(model)).toBe('AFTER');
+ });
+
+ it('is a no-op when the entity has no runtime binding', () => {
+ const setTile = vi.spyOn(TilemapAPI, 'setTile');
+ const m2 = new SceneModelImpl();
+ const c2 = new SceneCommandsImpl(m2, new EditorHistoryImpl());
+ m2.adopt(tilemapScene(), new Map()); // no runtime
+ c2.paintTiles(1, [{ x: 0, y: 0, tileId: 1 }]);
+ expect(setTile).not.toHaveBeenCalled();
+ });
+
+ it('records no undo step when the blob is unchanged', () => {
+ vi.spyOn(TilemapAPI, 'setTile').mockImplementation(() => {});
+ vi.spyOn(TilemapAPI, 'exportChunks').mockReturnValue('SAME'); // before === after
+ cmds.paintTiles(1, [{ x: 0, y: 0, tileId: 1 }]);
+ expect(history.canUndo()).toBe(false);
+ });
+});