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.

refactor(editor): route tilemap creation through the unified create pipeline

esengine785eabbabbbe
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.ts
index bdfb061bf..5ceceebc6 100644
--- a/desktop/src/engine/entitySources.ts
+++ b/desktop/src/engine/entitySources.ts
@@ -39,6 +39,8 @@ export interface EntitySource {
placement?: PlacementRule;
/** A prefab-linked source tags the subtree with this ref (instance = a delta). */
linkPrefabRef?: (ctx: CreateContext) => string | undefined;
+ /** Post-create side effects: out-of-band live-push, editor selection / panels. */
+ afterCreate?(ctx: CreateContext, rootId: EntityId): void;
}
/** Category display order in the Create popover (mirrors the Add-Component taxonomy style). */
@@ -71,6 +73,15 @@ export function spritePrefab(name: string, textureRef: string, size: { x: number
return preset(name, [['Transform', {}], ['Sprite', { texture: textureRef, size: { x: size.x, y: size.y } }]]);
}
+/**
+ * A Transform + TilemapLayer prefab whose `cellSize` (a vec2 → `{x, y}` in the model)
+ * is seeded from the tileset's tile size. The `.estileset` link is out-of-band and
+ * live-pushed separately (see createTilemap's afterCreate), not baked here.
+ */
+export function tilemapPrefab(name: string, cellSize: { x: number; y: number }): PrefabData {
+ return preset(name, [['Transform', {}], ['TilemapLayer', { cellSize: { x: cellSize.x, y: cellSize.y } }]]);
+}
+
/** A static preset source — its prefab is built once from the registered component defaults. */
function presetSource(id: string, label: string, category: string, icon: LucideIcon, comps: CompSpec[]): EntitySource {
const prefab = preset(label, comps);
@@ -127,9 +138,11 @@ function resolvePlacement(rule: PlacementRule | undefined, ctx: CreateContext):
*/
export async function createFromSource(source: EntitySource, ctx: CreateContext): Promise<EntityId | null> {
const prefab = await source.build(ctx);
- return SceneCommands.create(prefab, {
+ const id = SceneCommands.create(prefab, {
parent: resolvePlacement(source.placement, ctx),
position: ctx.position,
linkPrefabRef: source.linkPrefabRef?.(ctx),
});
+ if (id != null) source.afterCreate?.(ctx, id);
+ return id;
}
diff --git a/desktop/src/tilemap/createTilemap.ts b/desktop/src/tilemap/createTilemap.ts
index 51706dab3..4af7327a7 100644
--- a/desktop/src/tilemap/createTilemap.ts
+++ b/desktop/src/tilemap/createTilemap.ts
@@ -2,19 +2,52 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file createTilemap.ts
- * @brief Spawn a scene-embedded TilemapLayer entity from an .estileset —
- * the Unity/Godot model: the tilemap is a real,
- * paintable entity, the tileset is the reusable asset it references.
+ * @brief Spawn a scene-embedded TilemapLayer entity from an .estileset through the
+ * unified create pipeline (REARCH ENTITY_CREATION E3): `build` yields the
+ * Transform+TilemapLayer prefab (cellSize seeded from the tileset, one undo
+ * step); `afterCreate` links the tileset (out-of-band + live-push, its own
+ * undoable 'Set Tilesets' step so redo re-pushes) and opens the painter. The
+ * tileset stays the reusable asset the map references (Unity/Godot model).
*/
-
import { parseTileset } from 'esengine';
+import { Grid3x3 } from 'lucide-react';
import { SceneCommands } from '@/engine/SceneCommands';
+import { createFromSource, tilemapPrefab, type EntitySource } from '@/engine/entitySources';
import { useSelection } from '@/store/selectionStore';
import { useTilemapPaint } from '@/store/tilemapPaintStore';
import { ProjectStore } from '@/project/ProjectStore';
import { dockApi } from '@/layout/dockApi';
import { Toasts } from '@/store/Toasts';
+/**
+ * An EntitySource for a specific .estileset: cellSize is seeded from the tileset's tile
+ * size, and afterCreate links the tileset live + opens the painter. `tileWidth/Height`
+ * are read from the already-parsed tileset so `build` stays synchronous.
+ */
+function tilesetSource(tilesetPath: string, tilesetRef: string, tileWidth: number, tileHeight: number): EntitySource {
+ return {
+ id: `tileset:${tilesetPath}`,
+ label: 'Tilemap',
+ category: '2D',
+ icon: Grid3x3,
+ build: () => tilemapPrefab('Tilemap', { x: tileWidth, y: tileHeight }),
+ afterCreate: (_ctx, rootId) => {
+ // The .estileset link is out-of-band (carried in the model like the chunks blob).
+ // setLayerTilesets writes it AND live-pushes to the plugin so the fresh layer
+ // resolves its render table and is paintable immediately. It records its own
+ // 'Set Tilesets' undo step, so redo re-pushes (no reload needed).
+ SceneCommands.setLayerTilesets(rootId, [tilesetRef]);
+ useSelection.getState().select(rootId);
+ useTilemapPaint.getState().setTileset(tilesetPath);
+ useTilemapPaint.getState().setTool('brush');
+ // Dock the painter to the side so the Viewport stays visible (a center tab would
+ // hide what you paint on).
+ dockApi.openSidePanel('tilemap', 'tilemap', 'Tilemap', 'left', 300);
+ Toasts.push('Created tilemap — pick a brush to paint in the viewport', 'info');
+ },
+ };
+}
+
/** Create a TilemapLayer entity referencing the given .estileset, select it, and start painting. */
export async function createTilemapFromTileset(tilesetPath: string): Promise<void> {
const tilesetRef = ProjectStore.assetRef(tilesetPath); // .estileset → @uuid
@@ -29,31 +62,5 @@ export async function createTilemapFromTileset(tilesetPath: string): Promise<voi
Toasts.push(`Failed to read tileset: ${String(e)}`, 'error');
return;
}
-
- const sourceId = SceneCommands.addEntity();
- if (sourceId == null) return;
- SceneCommands.addComponent(sourceId, 'TilemapLayer');
- SceneCommands.beginGesture('Configure Tilemap');
- // cellSize is a per-layer authoring choice SEEDED from the tileset's tile size;
- // everything else — render table (texture/columns), animations, collision —
- // derives LIVE from the .estileset reference (tilemap sync resolves it and calls
- // setTilesets), so editing the tileset updates every map that references it.
- // The old flow copied texture/columns onto the component and baked
- // collidableTileIds into the model: three snapshots that went stale the moment
- // the tileset changed.
- SceneCommands.setField(sourceId, 'TilemapLayer', 'cellSize', 'vec2', [asset.tileWidth, asset.tileHeight]);
- SceneCommands.endGesture();
- // The .estileset link. Not a C++ field — carried losslessly in the model like the
- // chunks blob. setLayerTilesets also pushes it to the runtime plugin live (the
- // reconciler can't project an out-of-band field), so the fresh layer resolves its
- // render table and is paintable immediately, without a reload.
- SceneCommands.setLayerTilesets(sourceId, [tilesetRef]);
-
- useSelection.getState().select(sourceId);
- useTilemapPaint.getState().setTileset(tilesetPath);
- useTilemapPaint.getState().setTool('brush');
- // The painter is a palette companion to viewport painting — dock it to the side
- // so the Viewport stays visible (a center tab would hide what you paint on).
- dockApi.openSidePanel('tilemap', 'tilemap', 'Tilemap', 'left', 300);
- Toasts.push('Created tilemap — pick a brush to paint in the viewport', 'info');
+ await createFromSource(tilesetSource(tilesetPath, tilesetRef, asset.tileWidth, asset.tileHeight), { parent: null });
}
diff --git a/desktop/tests/entity-sources.test.ts b/desktop/tests/entity-sources.test.ts
index b46e472b2..f72fe9ace 100644
--- a/desktop/tests/entity-sources.test.ts
+++ b/desktop/tests/entity-sources.test.ts
@@ -8,7 +8,7 @@
* (not hardcoded), and search matches label/category/keyword. Pure TS.
*/
import { describe, it, expect } from 'vitest';
-import { ENTITY_SOURCES, matchSources, CREATE_CATEGORY_ORDER } from '@/engine/entitySources';
+import { ENTITY_SOURCES, matchSources, CREATE_CATEGORY_ORDER, tilemapPrefab } from '@/engine/entitySources';
const ctx = { parent: null };
@@ -49,4 +49,14 @@ describe('entitySources registry (Create-entity E2)', () => {
expect(matchSources(ENTITY_SOURCES, '')).toHaveLength(ENTITY_SOURCES.length);
expect(matchSources(ENTITY_SOURCES, 'zzznope')).toHaveLength(0);
});
+
+ it('tilemapPrefab seeds cellSize as a vec2 {x,y} on a Transform+TilemapLayer entity', () => {
+ const p = tilemapPrefab('Tilemap', { x: 32, y: 16 });
+ const root = p.entities.find((e) => e.prefabEntityId === p.rootEntityId)!;
+ const types = root.components.map((c) => c.type);
+ expect(types).toContain('Transform');
+ expect(types).toContain('TilemapLayer');
+ const layer = root.components.find((c) => c.type === 'TilemapLayer')!.data as { cellSize: { x: number; y: number } };
+ expect(layer.cellSize).toMatchObject({ x: 32, y: 16 });
+ });
});