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
feat(tilemap): native isometric/staggered/hexagonal map authoring in the editor
yhh175d5e0b37f5
diff --git a/desktop/src/commands/editorCommands.ts b/desktop/src/commands/editorCommands.tsindex a274b17c6..a941d6d59 100644--- a/desktop/src/commands/editorCommands.ts+++ b/desktop/src/commands/editorCommands.ts@@ -17,7 +17,6 @@ import { SceneModel } from '@/engine/SceneModel';import { hasEntityClipboard } from '@/engine/entityClipboard';import { ViewportController } from '@/engine/ViewportController';import { applyFxPreview } from '@/engine/fxPreview';-import { createTilemapFromTileset } from '@/tilemap/createTilemap';import { dockApi } from '@/layout/dockApi';import { EDITOR_MODES } from '@/mode/editorModes';import { activeMode } from '@/mode/activeMode';@@ -123,20 +122,16 @@ commands.register({label: t('cmd.tilemap.new'),category: t('cat.entity'),isEnabled: () => !!ProjectStore.getSnapshot(),- // A tilemap needs a tileset palette. Zero → guide the user to make one; exactly- // one → create straight away; many → let them pick (TilemapPickerDialog). The- // downstream createTilemapFromTileset does all the entity wiring either way.+ // A tilemap needs a tileset palette. Zero → guide the user to make one; otherwise+ // open the picker so they choose the orientation (orthogonal / iso / staggered /+ // hex) AND the tileset up front, like Tiled's New Map dialog. createTilemapFromTileset+ // does all the entity wiring; the picker just gathers the grid + palette choice.run: () => {const list = ProjectStore.listAssets('tileset');if (list.length === 0) {Toasts.push(t('toast.noTileset'), 'warn');return;}- if (list.length === 1) {- const path = ProjectStore.assetInfo(list[0].ref)?.path;- if (path) void createTilemapFromTileset(path);- return;- }editor().setTilemapPickerOpen(true);},});diff --git a/desktop/src/components/TilemapPickerDialog.tsx b/desktop/src/components/TilemapPickerDialog.tsxindex ff41d7d77..88c89b359 100644--- a/desktop/src/components/TilemapPickerDialog.tsx+++ b/desktop/src/components/TilemapPickerDialog.tsx@@ -1,49 +1,102 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file TilemapPickerDialog.tsx — the "New Tilemap" tileset chooser.+ * @file TilemapPickerDialog.tsx — the "New Tilemap" tileset + orientation chooser.* Opened by the `tilemap.new` command when the project has more than one- * `.estileset` (one → created directly, none → guided by a toast). Pick a- * tileset and `createTilemapFromTileset` does the full wiring (spawn the- * TilemapLayer entity, seed cellSize, live-sync the tileset, open the- * painter). A store-flag dialog like BuildDialog / SettingsDialog.+ * `.estileset` (one → created directly orthogonal, none → guided by a toast).+ * Pick an orientation (orthogonal / isometric / staggered / hexagonal, with+ * stagger axis+index and hex side length when relevant) and a tileset;+ * `createTilemapFromTileset` does the full wiring (spawn the TilemapLayer,+ * seed cellSize + grid, live-sync the tileset, open the painter).*/import { useState } from 'react';import { LayoutGrid } from 'lucide-react';import { Modal } from '@/components/Modal';import { SearchField } from '@/components/SearchField';+import { Segmented } from '@/components/Segmented';import { ProjectStore } from '@/project/ProjectStore';import { useEditorStore } from '@/store/editorStore';import { createTilemapFromTileset } from '@/tilemap/createTilemap';+import {+ TileOrientation, usesStagger, isHexOrientation,+ orientationOptions, staggerAxisOptions, staggerIndexOptions,+} from '@/tilemap/tileOrientation';+import type { TileGridConfig } from '@/engine/entitySources';import { t } from '@/i18n';export function TilemapPickerDialog() {const close = () => useEditorStore.getState().setTilemapPickerOpen(false);const [q, setQ] = useState('');+ const [orientation, setOrientation] = useState<number>(TileOrientation.Orthogonal);+ const [staggerAxis, setStaggerAxis] = useState(0);+ const [staggerIndex, setStaggerIndex] = useState(0);+ const [hexSide, setHexSide] = useState('');+const tilesets = ProjectStore.listAssets('tileset');const needle = q.trim().toLowerCase();- const shown = needle ? tilesets.filter((t) => t.name.toLowerCase().includes(needle)) : tilesets;+ const shown = needle ? tilesets.filter((ts) => ts.name.toLowerCase().includes(needle)) : tilesets;++ const stagger = usesStagger(orientation);+ const hex = isHexOrientation(orientation);const choose = (ref: string) => {const path = ProjectStore.assetInfo(ref)?.path;close();- if (path) void createTilemapFromTileset(path);+ if (!path) return;+ const grid: TileGridConfig = { orientation };+ if (stagger) { grid.staggerAxis = staggerAxis; grid.staggerIndex = staggerIndex; }+ if (hex) { const s = Number(hexSide); if (Number.isFinite(s) && s > 0) grid.hexSideLength = s; }+ void createTilemapFromTileset(path, grid);};return (<Modal title={t('cmd.tilemap.new')} onClose={close} width={440}><div className="tmpick"><p className="tmpick__hint">{t('tile.pick.hint')}</p>++ <div className="tmpick__orient">+ <label className="tmpick__flabel">{t('tile.orient.label')}</label>+ <Segmented+ grow+ ariaLabel={t('tile.orient.label')}+ value={String(orientation)}+ options={orientationOptions()}+ onChange={(v) => setOrientation(Number(v))}+ />+ {stagger && (+ <div className="tmpick__grid2">+ <label className="tmpick__flabel">{t('tile.orient.staggerAxis')}</label>+ <Segmented grow value={String(staggerAxis)} options={staggerAxisOptions()} onChange={(v) => setStaggerAxis(Number(v))} />+ <label className="tmpick__flabel">{t('tile.orient.staggerIndex')}</label>+ <Segmented grow value={String(staggerIndex)} options={staggerIndexOptions()} onChange={(v) => setStaggerIndex(Number(v))} />+ </div>+ )}+ {hex && (+ <div className="tmpick__row">+ <label className="tmpick__flabel">{t('tile.orient.hexSide')}</label>+ <input+ className="field tmpick__num"+ type="number"+ min={0}+ step={1}+ placeholder="auto"+ value={hexSide}+ onChange={(e) => setHexSide(e.target.value)}+ />+ </div>+ )}+ </div>+<SearchField className="tmpick__search" autoFocus placeholder={t('tile.pick.search')} value={q} onChange={setQ} />{shown.length === 0 ? (<div className="empty-line">{t('tile.pick.noMatch')}</div>) : (<div className="tmpick__list">- {shown.map((t) => (- <button key={t.ref} type="button" className="tmpick__item" onClick={() => choose(t.ref)}>+ {shown.map((ts) => (+ <button key={ts.ref} type="button" className="tmpick__item" onClick={() => choose(ts.ref)}><LayoutGrid size={15} className="tmpick__icon" />- <span className="tmpick__name">{t.name.replace(/\.estileset$/, '')}</span>- <span className="tmpick__path">{t.path}</span>+ <span className="tmpick__name">{ts.name.replace(/\.estileset$/, '')}</span>+ <span className="tmpick__path">{ts.path}</span></button>))}</div>diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.tsindex 0ab2c161c..4411c8801 100644--- a/desktop/src/engine/ViewportController.ts+++ b/desktop/src/engine/ViewportController.ts@@ -7,8 +7,9 @@ import {RevoluteJoint, DistanceJoint, PrismaticJoint, WeldJoint, WheelJoint, MotorJoint,UINode, UICameraInfo, screenToUiWorld, uiWorldToScreen, uiPickAllWorld, type UICameraData,TilemapLayer, TilemapAPI, decodeTilemapChunks, tileCollisionOutlines,+ tileCellCenter, tileCellOutline, isNonOrthogonal,readColliderShapes, colliderShapeOutline, shapeCenter,- type TilesetModel, type TileCollisionPiece,+ type TilesetModel, type TileCollisionPiece, type TileGridParams,} from 'esengine';import type { EntityId } from '@/types';import { EngineHost } from './EngineHost';@@ -889,6 +890,107 @@ export const ViewportController = {return { solid, sensor, onewayLine, onewayHead };},+ // ── Orientation-aware tile-grid overlay ─────────────────────────────────────+ // Non-orthogonal maps (iso / staggered / hex) can't be drawn by the engine's square+ // grid or the axis-aligned div ghost, so the editor draws their cells as shaped SVG+ // polygons. All three read the SAME cell geometry the runtime places tiles with+ // ({@link tileCellCenter}/{@link tileCellOutline}), so overlay and rendered tiles line up.++ /** The selected layer's grid layout + world origin, or null (not a tilemap / no runtime). */+ tileGridParams(id: EntityId): { params: TileGridParams; origin: { x: number; y: number } } | null {+ const comp = SceneModel.entityBySource(id)?.components.find((c) => c.type === 'TilemapLayer');+ const d = comp?.data as {+ cellSize?: { x: number; y: number }; orientation?: number; hexSideLength?: number;+ staggerAxis?: number; staggerIndex?: number;+ } | undefined;+ if (!d?.cellSize) return null;+ const rt = SceneModel.runtimeFor(id);+ const origin = rt != null ? this.getEntityWorldXY(rt) : null;+ if (!origin) return null;+ return {+ params: {+ orientation: d.orientation ?? 0,+ tileWidth: d.cellSize.x, tileHeight: d.cellSize.y,+ hexSideLength: d.hexSideLength ?? 0,+ staggerAxisX: (d.staggerAxis ?? 0) === 1,+ staggerIndexEven: (d.staggerIndex ?? 0) === 1,+ },+ origin,+ };+ },++ /** True when the selected layer uses a non-orthogonal grid (drives the SVG overlay). */+ tileLayerIsNonOrthogonal(id: EntityId): boolean {+ const gp = this.tileGridParams(id);+ return !!gp && isNonOrthogonal(gp.params.orientation);+ },++ /**+ * SVG path `d` for the outlines of the given tile cells (each a closed polygon in the+ * layer's orientation). `cullPad` (client px) drops cells whose center projects well+ * off-canvas so the grid path stays small when zoomed in.+ */+ projectTileCellPaths(+ params: TileGridParams, origin: { x: number; y: number },+ cells: Iterable<{ x: number; y: number }>, cullPad = Infinity,+ ): string {+ const outline = tileCellOutline(params);+ const canvas = EngineHost.canvas;+ const rect = cullPad === Infinity || !canvas ? null : canvas.getBoundingClientRect();+ let d = '';+ for (const cell of cells) {+ const c = tileCellCenter(params, cell.x, cell.y);+ const cx = origin.x + c.x;+ const cy = origin.y + c.y;+ if (rect) {+ const sc = this.worldToClient(cx, cy);+ if (!sc || sc.x < rect.left - cullPad || sc.x > rect.right + cullPad+ || sc.y < rect.top - cullPad || sc.y > rect.bottom + cullPad) continue;+ }+ let sub = '';+ for (let i = 0; i < outline.length; i++) {+ const s = this.worldToClient(cx + outline[i].x, cy + outline[i].y);+ if (!s) { sub = ''; break; }+ sub += `${i ? 'L' : 'M'}${s.x.toFixed(1)},${s.y.toFixed(1)}`;+ }+ if (sub) d += `${sub}Z`;+ }+ return d;+ },++ /**+ * The visible tile-index bbox for the grid overlay (the on-screen corners mapped back+ * to tile coords, padded for iso/hex diamonds that reach past the corner samples), or+ * null when it would exceed `cap` cells (too zoomed out to draw a useful grid).+ */+ visibleTileRange(+ id: EntityId, origin: { x: number; y: number }, cap: number,+ ): { x0: number; y0: number; x1: number; y1: number } | null {+ const rt = SceneModel.runtimeFor(id);+ const canvas = EngineHost.canvas;+ if (rt == null || !canvas) return null;+ const rect = canvas.getBoundingClientRect();+ const corners = [+ this.canvasToWorld(rect.left, rect.top),+ this.canvasToWorld(rect.right, rect.top),+ this.canvasToWorld(rect.left, rect.bottom),+ this.canvasToWorld(rect.right, rect.bottom),+ ];+ let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;+ for (const c of corners) {+ if (!c) continue;+ const t = TilemapAPI.worldToTile(rt, c.x, c.y, origin.x, origin.y);+ x0 = Math.min(x0, t.x); x1 = Math.max(x1, t.x);+ y0 = Math.min(y0, t.y); y1 = Math.max(y1, t.y);+ }+ if (!Number.isFinite(x0)) return null;+ const PAD = 3; // partial cells + iso/hex extremes past the corner samples+ x0 = Math.floor(x0) - PAD; y0 = Math.floor(y0) - PAD;+ x1 = Math.ceil(x1) + PAD; y1 = Math.ceil(y1) + PAD;+ if ((x1 - x0 + 1) * (y1 - y0 + 1) > cap) return null;+ return { x0, y0, x1, y1 };+ },+/** (entity, joint-type) pairs for every scene-authored joint — the joint-gizmo set. */jointGizmoKeys(): Array<{ id: EntityId; type: JointGizmoType }> {const world = EngineHost.world;diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.tsindex d4e31d5cc..388d57e8f 100644--- a/desktop/src/engine/entitySources.ts+++ b/desktop/src/engine/entitySources.ts@@ -108,15 +108,35 @@ export function animatedSpritePrefab(]);}+/** Grid layout for a new tilemap (subset of TilemapLayer). Values match the C+++ * TilemapOrientation / TilemapStaggerAxis / TilemapStaggerIndex enums. Only the+ * non-default fields are baked into the prefab, so an orthogonal map stays clean. */+export interface TileGridConfig {+ /** 0 orthogonal · 1 isometric · 2 staggered · 3 hexagonal. */+ orientation?: number;+ hexSideLength?: number;+ /** 0 = Y (rows stagger) · 1 = X (columns stagger). */+ staggerAxis?: number;+ /** 0 = odd · 1 = even. */+ staggerIndex?: number;+}+/*** A Transform + TilemapLayer prefab whose `cellSize` (a vec2 → `{x, y}` in the model)* is seeded from the tileset's tile size. `tilesetRef` bakes the out-of-band* `.estileset` link into the prefab, so it rides the single create step into the* model; the Reconciler live-pushes it to the plugin on spawn (create AND* redo/reload restore it), which is why creation needs no setLayerTilesets step.+ * `grid` seeds the orientation/stagger fields (omitted when orthogonal-default).*/-export function tilemapPrefab(name: string, cellSize: { x: number; y: number }, tilesetRef?: string): PrefabData {+export function tilemapPrefab(+ name: string, cellSize: { x: number; y: number }, tilesetRef?: string, grid?: TileGridConfig,+): PrefabData {const layer: Record<string, unknown> = { cellSize: { x: cellSize.x, y: cellSize.y } };+ if (grid?.orientation) layer.orientation = grid.orientation;+ if (grid?.hexSideLength) layer.hexSideLength = grid.hexSideLength;+ if (grid?.staggerAxis) layer.staggerAxis = grid.staggerAxis;+ if (grid?.staggerIndex) layer.staggerIndex = grid.staggerIndex;if (tilesetRef) {layer.tilesetAssets = [tilesetRef];layer.tilesetAsset = tilesetRef; // back-compat singular first tilesetdiff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.tsindex 5abc6362f..47c0e000a 100644--- a/desktop/src/engine/schema.ts+++ b/desktop/src/engine/schema.ts@@ -1,6 +1,6 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import { getAllRegisteredComponents, getUserComponents, getComponent, getComponentAssetFieldDescriptors, getComponentSpineFieldDescriptor, getComponentFieldMeta, Light2DType } from 'esengine';+import { getAllRegisteredComponents, getUserComponents, getComponent, getComponentAssetFieldDescriptors, getComponentSpineFieldDescriptor, getComponentFieldMeta, Light2DType, usesStagger, isHexOrientation } from 'esengine';import type { App, SceneData } from 'esengine';import type { NodeKind, InspectorField, EnumOption, GradientValue, CurveValue } from '@/types';@@ -553,6 +553,18 @@ function fieldFor(* registered default. The caller diffs `value` vs `defaultValue` to mark* overrides; an entity with no prefab base just compares against the default.*/+// Fields that only apply to some states of the SAME component — hidden from the+// inspector when inert so the panel shows just the controls that matter. Currently+// the tilemap stagger/hex fields, gated on the layer's orientation (an orthogonal or+// isometric map has no stagger; only hexagonal reads the side length).+function isConditionallyHidden(compType: string, key: string, data: Record<string, unknown>): boolean {+ if (compType !== 'TilemapLayer') return false;+ const orientation = Number(data.orientation) || 0;+ if (key === 'hexSideLength') return !isHexOrientation(orientation);+ if (key === 'staggerAxis' || key === 'staggerIndex') return !usesStagger(orientation);+ return false;+}+export function inspectorFields(compType: string,data: Record<string, unknown>,@@ -567,6 +579,7 @@ export function inspectorFields(const fields: InspectorField[] = [];for (const key of keys) {if (DERIVED_FIELDS.has(key)) continue;+ if (isConditionallyHidden(compType, key, data)) continue;const value = key in data ? data[key] : defaults?.[key];const f = fieldFor(compType, key, value, colorKeys.has(key));if (!f) continue;diff --git a/desktop/src/i18n/messages/tile.ts b/desktop/src/i18n/messages/tile.tsindex 2a0ac368b..cd0ab3223 100644--- a/desktop/src/i18n/messages/tile.ts+++ b/desktop/src/i18n/messages/tile.ts@@ -185,6 +185,20 @@ export const tileMessages = defineMessages({'tile.pick.search': { en: 'Search tilesets…', zh: '搜索瓦片集…' },'tile.pick.noMatch': { en: 'No matching tilesets', zh: '没有匹配的瓦片集' },+ // — Orientation picker (New-Tilemap dialog + inspector labels) —+ 'tile.orient.label': { en: 'Orientation', zh: '朝向' },+ 'tile.orient.orthogonal': { en: 'Orthogonal', zh: '正交' },+ 'tile.orient.isometric': { en: 'Isometric', zh: '等距' },+ 'tile.orient.staggered': { en: 'Staggered', zh: '交错' },+ 'tile.orient.hexagonal': { en: 'Hexagonal', zh: '六边形' },+ 'tile.orient.staggerAxis': { en: 'Stagger axis', zh: '交错轴' },+ 'tile.orient.staggerIndex': { en: 'Stagger index', zh: '交错序号' },+ 'tile.orient.axisY': { en: 'Y (rows)', zh: 'Y(行)' },+ 'tile.orient.axisX': { en: 'X (columns)', zh: 'X(列)' },+ 'tile.orient.odd': { en: 'Odd', zh: '奇数' },+ 'tile.orient.even': { en: 'Even', zh: '偶数' },+ 'tile.orient.hexSide': { en: 'Hex side (px)', zh: '六边形边长(px)' },+// — Dock panel title (the Tileset editor tab) —'tile.panelTileset': { en: 'Tileset', zh: '瓦片集' },diff --git a/desktop/src/main.tsx b/desktop/src/main.tsxindex 4e2343e7c..d7192fedf 100644--- a/desktop/src/main.tsx+++ b/desktop/src/main.tsx@@ -47,7 +47,9 @@ import { EngineHost } from './engine/EngineHost';import { Particle, getComponent } from 'esengine';import { applyFxPreview, initFxPreviewEditRestart } from './engine/fxPreview';import { commands } from './commands/registry';-import { ENTITY_SOURCES, sourceById, createFromSource } from './engine/entitySources';+import { ENTITY_SOURCES, sourceById, createFromSource, type TileGridConfig } from './engine/entitySources';+import { createTilemapFromTileset } from './tilemap/createTilemap';+import { SceneCommands } from './engine/SceneCommands';import { ViewportController } from './engine/ViewportController';import { PerfMonitor } from './engine/PerfMonitor';import { LogStore } from './store/LogStore';@@ -133,6 +135,12 @@ if (new URLSearchParams(location.search).has('automation')) {createSceneFile: (destDir: string) => ProjectStore.createSceneFile(destDir),/** The Create-popover catalog: every ready-made entity the editor can spawn. */listEntityTemplates: () => ENTITY_SOURCES.map(({ id, label, category }) => ({ id, label, category })),+ /** Create a TilemapLayer from an .estileset with an optional grid layout+ * (orientation/stagger/hex) — drives the New-Tilemap flow headlessly. */+ createTilemap: (tilesetPath: string, grid?: TileGridConfig) => createTilemapFromTileset(tilesetPath, grid),+ /** Paint tiles into a TilemapLayer SOURCE entity (one undo step) — for shot tests. */+ paintTiles: (sourceId: number, edits: { x: number; y: number; tileId: number }[]) =>+ SceneCommands.paintTiles(sourceId, edits),/** Spawn a ready-made entity through the one create pipeline (menu/DnD parity). */createEntity: async (sourceId: string, opts?: { parent?: number | null; x?: number; y?: number }) => {const source = sourceById(sourceId);diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsxindex 778b86397..1ed2d388d 100644--- a/desktop/src/panels/Viewport.tsx+++ b/desktop/src/panels/Viewport.tsx@@ -15,7 +15,7 @@ import { activeMode, activeModeOverlays } from '@/mode/activeMode';import { useEditorMode } from '@/store/editorModeStore';import { RESOLUTION_PRESETS, RESOLUTION_PRESET_BY_ID, DESIGN_RESOLUTION_PRESETS, deviceDims } from '@/mode/resolutionPresets';import { buildStampGhost } from '@/tools/tileStampGhost';-import { TilemapAPI, tileIdOf, UINode, DimensionUnit, computeEffectiveOrthoSize, type TileCollisionPiece, type TilesetModel } from 'esengine';+import { TilemapAPI, tileIdOf, isNonOrthogonal, UINode, DimensionUnit, computeEffectiveOrthoSize, type TileCollisionPiece, type TilesetModel } from 'esengine';import { commands } from '@/commands';import { MOD_LABEL } from '@/commands/keybinding';import { EngineHost } from '@/engine/EngineHost';@@ -45,6 +45,10 @@ import { selectionPivot, gizmoScreenAngleRad } from '@/tools/transformTools';import { Marquee } from '@/tools/marquee';import { TilePaintPreview } from '@/tools/tilePreview';+// Cap on the non-orthogonal grid overlay's drawn cells — beyond this the view is too+// zoomed out for a cell grid to read, so it's skipped rather than churning a huge path.+const TILE_GRID_CELL_CAP = 4000;+// A React pointer event → the tool-facing PointerInput (no DOM coupling in tools).const toInput = (e: ReactPointerEvent): PointerInput => ({clientX: e.clientX, clientY: e.clientY, pointerId: e.pointerId,@@ -752,6 +756,10 @@ export function Viewport() {const tilePaintRef = useRef<HTMLDivElement>(null);const paintPoolRef = useRef<HTMLDivElement[]>([]);const hoverTileRef = useRef<{ x: number; y: number } | null>(null);+ // Orientation-aware overlay for non-orthogonal maps (iso/staggered/hex): one SVG+ // whose shaped-cell paths (grid + selection + gesture + hover) replace the square+ // engine grid and the axis-aligned div ghost, which only fit an orthogonal grid.+ const tileGridRef = useRef<SVGSVGElement | null>(null);// Camera pan (middle/right drag) is built-in navigation, separate from tools.const panRef = useRef<{ px: number; py: number } | null>(null);// The tool that owns the in-progress left-button stroke (move/up route to it).@@ -869,9 +877,12 @@ export function Viewport() {// origin-offset support lands.)useEffect(() => {if (engine.status !== 'ready') return;+ // Non-orthogonal maps draw their own shaped grid (viewport__tilegrid), so turn the+ // engine's square grid off for them — a square grid over an iso/hex map misleads.+ const nonOrtho = primaryId != null && ViewportController.tileLayerIsNonOrthogonal(primaryId);const cell = selectedTilemapCellSize();- EngineHost.setGrid(showGrid, cell ? cell.x : snapStep);- }, [showGrid, snapStep, primaryId, engine.status]);+ EngineHost.setGrid(showGrid && !nonOrtho, cell ? cell.x : snapStep);+ }, [showGrid, snapStep, primaryId, engine.status, dataRev]);// Play In Viewport (UE5 PIE): host the realm iframe over the stage while playing// here. The host div is PERSISTENT (mounted whenever the viewport is the play@@ -1082,13 +1093,16 @@ export function Viewport() {const sid = useSelection.getState().selectedId;const rt = ready && sid != null ? SceneModel.runtimeFor(sid) : undefined;const paint = useTilemapPaint.getState();+ // Non-orthogonal maps route ALL tile overlays through the shaped SVG below, so the+ // axis-aligned div marquee/ghost/preview stay hidden (their corner math is square).+ const nonOrtho = ready && sid != null && ViewportController.tileLayerIsNonOrthogonal(sid);const tsel = paint.tool === 'select' ? paint.selection : null;const layer = ready && sid != null? SceneModel.entityBySource(sid)?.components.find((c) => c.type === 'TilemapLayer'): undefined;const cs = layer?.data as { cellSize?: { x: number; y: number } } | undefined;const origin = ready && rt != null ? ViewportController.getEntityWorldXY(rt) : null;- if (tsel && cs?.cellSize && origin) {+ if (tsel && cs?.cellSize && origin && !nonOrtho) {const x0 = Math.min(tsel.x0, tsel.x1);const y0 = Math.min(tsel.y0, tsel.y1);const x1 = Math.max(tsel.x0, tsel.x1);@@ -1117,7 +1131,7 @@ export function Viewport() {// Random brush lays ONE sampled tile per cell, so its footprint is 1×1 — only a// pattern brush (or erase, which clears the whole w×h) previews at the stamp size.const stampSized = paint.tool === 'erase' || (paint.tool === 'brush' && !paint.randomBrush);- const canFoot = !!(paint.tool && !gesturing && hov && cs?.cellSize && origin);+ const canFoot = !!(paint.tool && !gesturing && hov && cs?.cellSize && origin && !nonOrtho);// Footprint corners in client px (fw×fh cells at the hovered cell).let ftl: { x: number; y: number } | null = null;let fbr: { x: number; y: number } | null = null;@@ -1163,7 +1177,7 @@ export function Viewport() {const shape = TilePaintPreview.get();const pool = paintPoolRef.current;let used = 0;- if (shape && cs?.cellSize && origin) {+ if (shape && cs?.cellSize && origin && !nonOrtho) {const cw = cs.cellSize.x;const ch = cs.cellSize.y;const place = (tx: number, ty: number, w: number, h: number): void => {@@ -1197,6 +1211,71 @@ export function Viewport() {}}+ // Orientation-aware tile overlay (iso / staggered / hex): the shaped grid + the+ // selection / gesture-preview / hover cells, all built from the SAME cell geometry+ // the runtime places tiles with, so the outlines sit exactly on the drawn tiles.+ const tgSvg = tileGridRef.current;+ if (tgSvg) {+ const sid = useSelection.getState().selectedId;+ const gp = ready && sid != null && !useEditorStore.getState().isPlaying+ ? ViewportController.tileGridParams(sid) : null;+ const setD = (sel: string, d: string) => {+ const el = tgSvg.querySelector(sel) as SVGPathElement | null;+ if (el) el.setAttribute('d', d);+ };+ if (gp && sid != null && isNonOrthogonal(gp.params.orientation)) {+ const { params, origin } = gp;+ const paint = useTilemapPaint.getState();+ const rangeCells = (x0: number, y0: number, x1: number, y1: number): { x: number; y: number }[] => {+ const cells: { x: number; y: number }[] = [];+ for (let ty = y0; ty <= y1; ty++) for (let tx = x0; tx <= x1; tx++) cells.push({ x: tx, y: ty });+ return cells;+ };+ // Grid: visible cells, faint. Off when the grid flag is off or too zoomed out.+ let gridD = '';+ if (useEditorStore.getState().showGrid) {+ const range = ViewportController.visibleTileRange(sid, origin, TILE_GRID_CELL_CAP);+ if (range) {+ gridD = ViewportController.projectTileCellPaths(+ params, origin, rangeCells(range.x0, range.y0, range.x1, range.y1), 96,+ );+ }+ }+ setD('.tg-grid', gridD);+ // Selection marquee cells.+ const sel = paint.tool === 'select' ? paint.selection : null;+ setD('.tg-select', sel+ ? ViewportController.projectTileCellPaths(params, origin, rangeCells(+ Math.min(sel.x0, sel.x1), Math.min(sel.y0, sel.y1), Math.max(sel.x0, sel.x1), Math.max(sel.y0, sel.y1),+ ))+ : '');+ // Gesture preview (rect fill box / line / ellipse cells).+ const shape = TilePaintPreview.get();+ let prevD = '';+ if (shape) {+ const cells = shape.kind === 'rect'+ ? rangeCells(Math.min(shape.x0, shape.x1), Math.min(shape.y0, shape.y1), Math.max(shape.x0, shape.x1), Math.max(shape.y0, shape.y1))+ : shape.cells;+ prevD = ViewportController.projectTileCellPaths(params, origin, cells);+ }+ setD('.tg-preview', prevD);+ // Hover footprint (the cells the brush will lay), unless a gesture is drawing.+ const hov = hoverTileRef.current;+ let hovD = '';+ if (hov && paint.tool && paint.tool !== 'select' && !shape) {+ const stampSized = paint.tool === 'erase' || (paint.tool === 'brush' && !paint.randomBrush);+ const cells: { x: number; y: number }[] = stampSized+ ? rangeCells(hov.x, hov.y, hov.x + paint.stamp.w - 1, hov.y + paint.stamp.h - 1)+ : [{ x: hov.x, y: hov.y }];+ hovD = ViewportController.projectTileCellPaths(params, origin, cells);+ }+ setD('.tg-hover', hovD);+ tgSvg.style.display = '';+ } else {+ tgSvg.style.display = 'none';+ }+ }+// Scene-camera gizmos — only in edit mode (in play the viewport IS the// game camera), and only when gizmos are on.const camsOn = ready && showG && !useEditorStore.getState().isPlaying;@@ -1901,6 +1980,16 @@ export function Viewport() {<path className="tc-oneway-head" d="" /></svg>+ {/* Orientation-aware tile overlay for iso/staggered/hex maps: shaped grid + selection+ + gesture preview + hover cells (the square engine grid + div ghost can't draw a+ diamond/hex). The rAF writes each path's data; hidden for orthogonal maps. */}+ <svg className="viewport__tilegrid" ref={tileGridRef} aria-hidden="true" style={{ display: 'none' }}>+ <path className="tg-grid" d="" />+ <path className="tg-select" d="" />+ <path className="tg-preview" d="" />+ <path className="tg-hover" d="" />+ </svg>+{/* Collider gizmos: a full-viewport SVG per collider (box polygon / circle),positioned in absolute canvas-relative CSS px by the rAF. */}{colliderIds.map((id) => (diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.cssindex 57a8f986e..483be6b97 100644--- a/desktop/src/theme/app.css+++ b/desktop/src/theme/app.css@@ -485,6 +485,42 @@ body.thumb-capture .viewport > :not(.viewport__stage):not(.viewport__play) {fill: var(--gizmo-collider);}+/* Orientation-aware tile overlay (iso/staggered/hex): shaped-cell paths the rAF fills.+ Grid = faint lattice; select/preview/hover reuse the tile accent like the ortho div+ overlays so the two modes read the same. Spans the viewport; rAF writes client px. */+.viewport__tilegrid {+ position: absolute;+ inset: 0;+ width: 100%;+ height: 100%;+ z-index: 2;+ pointer-events: none;+ overflow: visible;+}+.viewport__tilegrid .tg-grid {+ fill: none;+ stroke: rgba(255, 255, 255, 0.11);+ stroke-width: 1;+}+.viewport__tilegrid .tg-select {+ fill: color-mix(in srgb, var(--gizmo-tile) 12%, transparent);+ stroke: var(--gizmo-tile);+ stroke-width: 1;+ stroke-dasharray: 4 3;+}+.viewport__tilegrid .tg-preview {+ fill: color-mix(in srgb, var(--gizmo-tile) 22%, transparent);+ stroke: color-mix(in srgb, var(--gizmo-tile) 70%, transparent);+ stroke-width: 1;+ stroke-linejoin: round;+}+.viewport__tilegrid .tg-hover {+ fill: rgba(255, 255, 255, 0.1);+ stroke: rgba(255, 255, 255, 0.85);+ stroke-width: 1.25;+ stroke-linejoin: round;+}+/* Joint link gizmo: anchor dots + link line (own body ↔ connected body), theprismatic/wheel slide axis, and the motor target-velocity arrow. The SVG spansthe viewport; the rAF writes absolute canvas-relative px. */diff --git a/desktop/src/theme/menus.css b/desktop/src/theme/menus.cssindex 7b46b0078..3ddde15b5 100644--- a/desktop/src/theme/menus.css+++ b/desktop/src/theme/menus.css@@ -143,6 +143,12 @@.tmpick__icon { flex: 0 0 auto; color: var(--text-mute); }.tmpick__name { flex: 0 0 auto; font-weight: 600; }.tmpick__path { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: var(--fs-2xs); color: var(--text-mute); text-align: right; }+/* Orientation chooser block */+.tmpick__orient { display: flex; flex-direction: column; gap: 7px; padding: 10px; background: var(--srf-3); border-radius: var(--r-md); }+.tmpick__flabel { font-size: var(--fs-2xs); font-weight: 600; color: var(--text-mute); text-transform: uppercase; letter-spacing: 0.04em; }+.tmpick__grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: 5px 10px; align-items: center; }+.tmpick__row { display: flex; align-items: center; gap: 10px; }+.tmpick__num { width: 90px; height: 26px; }/* ── Package / Build dialog ── */.build { display: flex; flex-direction: column; gap: 12px; }diff --git a/desktop/src/tilemap/createTilemap.ts b/desktop/src/tilemap/createTilemap.tsindex 499a38f3f..ce525bfa8 100644--- a/desktop/src/tilemap/createTilemap.ts+++ b/desktop/src/tilemap/createTilemap.ts@@ -11,7 +11,7 @@*/import { parseTileset } from 'esengine';import { Grid3x3 } from 'lucide-react';-import { createFromSource, tilemapPrefab, type EntitySource } from '@/engine/entitySources';+import { createFromSource, tilemapPrefab, type EntitySource, type TileGridConfig } from '@/engine/entitySources';import { useSelection } from '@/store/selectionStore';import { useTilemapPaint } from '@/store/tilemapPaintStore';import { ProjectStore } from '@/project/ProjectStore';@@ -24,7 +24,9 @@ import { t } from '@/i18n';* 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 {+function tilesetSource(+ tilesetPath: string, tilesetRef: string, tileWidth: number, tileHeight: number, grid?: TileGridConfig,+): EntitySource {return {id: `tileset:${tilesetPath}`,label: 'Tilemap',@@ -32,7 +34,7 @@ function tilesetSource(tilesetPath: string, tilesetRef: string, tileWidth: numbeicon: Grid3x3,// tilesetRef bakes the link into the prefab; the Reconciler live-pushes it on// spawn/redo, so the map is a single undoable create with no wiring step.- build: () => tilemapPrefab('Tilemap', { x: tileWidth, y: tileHeight }, tilesetRef),+ build: () => tilemapPrefab('Tilemap', { x: tileWidth, y: tileHeight }, tilesetRef, grid),afterCreate: (_ctx, rootId) => {useSelection.getState().select(rootId);useTilemapPaint.getState().setTileset(tilesetPath);@@ -45,8 +47,9 @@ function tilesetSource(tilesetPath: string, tilesetRef: string, tileWidth: numbe};}-/** Create a TilemapLayer entity referencing the given .estileset, select it, and start painting. */-export async function createTilemapFromTileset(tilesetPath: string): Promise<void> {+/** Create a TilemapLayer entity referencing the given .estileset, select it, and start+ * painting. `grid` sets the orientation/stagger layout (defaults to orthogonal). */+export async function createTilemapFromTileset(tilesetPath: string, grid?: TileGridConfig): Promise<void> {const tilesetRef = ProjectStore.assetRef(tilesetPath); // .estileset → @uuidif (!tilesetRef) {Toasts.push(t('tile.toast.untracked'), 'error');@@ -59,5 +62,7 @@ export async function createTilemapFromTileset(tilesetPath: string): Promise<voiToasts.push(t('tile.toast.readFailed', { error: String(e) }), 'error');return;}- await createFromSource(tilesetSource(tilesetPath, tilesetRef, asset.tileWidth, asset.tileHeight), { parent: null });+ await createFromSource(+ tilesetSource(tilesetPath, tilesetRef, asset.tileWidth, asset.tileHeight, grid), { parent: null },+ );}diff --git a/desktop/src/tilemap/tileOrientation.ts b/desktop/src/tilemap/tileOrientation.tsnew file mode 100644index 000000000..4b47b76fd--- /dev/null+++ b/desktop/src/tilemap/tileOrientation.ts@@ -0,0 +1,46 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file tileOrientation.ts+ * @brief Shared editor vocabulary for tilemap orientation — the i18n'd option lists+ * for the New-Tilemap dialog + inspector, over the numeric values that match+ * the C++ TilemapOrientation / TilemapStaggerAxis / TilemapStaggerIndex enums.+ * Geometry predicates (usesStagger / isHexOrientation) come from esengine so+ * the editor and runtime agree on which layouts read the stagger/hex fields.+ */+import { TileOrientation } from 'esengine';+import type { SegmentedOption } from '@/components/Segmented';+import { t } from '@/i18n';++export { TileOrientation, usesStagger, isHexOrientation } from 'esengine';++/** staggerAxis field values (match C++ TilemapStaggerAxis). */+export const STAGGER_AXIS_Y = 0;+export const STAGGER_AXIS_X = 1;+/** staggerIndex field values (match C++ TilemapStaggerIndex). */+export const STAGGER_INDEX_ODD = 0;+export const STAGGER_INDEX_EVEN = 1;++/** Orientation segments, in the C++ enum order (value = the numeric field). */+export function orientationOptions(): SegmentedOption<string>[] {+ return [+ { value: String(TileOrientation.Orthogonal), label: t('tile.orient.orthogonal') },+ { value: String(TileOrientation.Isometric), label: t('tile.orient.isometric') },+ { value: String(TileOrientation.Staggered), label: t('tile.orient.staggered') },+ { value: String(TileOrientation.Hexagonal), label: t('tile.orient.hexagonal') },+ ];+}++export function staggerAxisOptions(): SegmentedOption<string>[] {+ return [+ { value: String(STAGGER_AXIS_Y), label: t('tile.orient.axisY') },+ { value: String(STAGGER_AXIS_X), label: t('tile.orient.axisX') },+ ];+}++export function staggerIndexOptions(): SegmentedOption<string>[] {+ return [+ { value: String(STAGGER_INDEX_ODD), label: t('tile.orient.odd') },+ { value: String(STAGGER_INDEX_EVEN), label: t('tile.orient.even') },+ ];+}diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.tsindex 35646343c..bd965335b 100644--- a/sdk/src/component.generated.ts+++ b/sdk/src/component.generated.ts@@ -15,7 +15,7 @@ import type { Dimension, Padding } from './wasm.generated';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = 'bde213b560e9ce4c';+export const ABI_LAYOUT_HASH = '4e0613ea05e766a3';export interface AssetFieldMeta {field: string;@@ -519,6 +519,10 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {TilemapLayer: {defaults: {cellSize: { x: 32, y: 32 },+ orientation: 0,+ hexSideLength: 0,+ staggerAxis: 0,+ staggerIndex: 0,originOffset: { x: 0, y: 0 },tileset: 0,tilesetColumns: 1,@@ -534,6 +538,10 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {colorFields: ['tintColor'],animatableFields: ['tintColor.r', 'tintColor.g', 'tintColor.b', 'tintColor.a', 'opacity'],fields: {+ orientation: { enum: [{ label: 'Orthogonal', value: 0 }, { label: 'Isometric', value: 1 }, { label: 'Staggered', value: 2 }, { label: 'Hexagonal', value: 3 }], tooltip: "Grid layout: orthogonal, isometric, staggered, or hexagonal." },+ hexSideLength: { min: 0, step: 1, tooltip: "Hexagonal side length in px (0 = a regular pointy hex = tileHeight/2). Ignored unless orientation is Hexagonal." },+ staggerAxis: { enum: [{ label: 'Y', value: 0 }, { label: 'X', value: 1 }], tooltip: "Stagger axis (staggered/hex): Y shifts rows, X shifts columns." },+ staggerIndex: { enum: [{ label: 'Odd', value: 0 }, { label: 'Even', value: 1 }], tooltip: "Which lines carry the half-cell shift (staggered/hex)." },tilesetColumns: { min: 1, step: 1 },tilesetRows: { min: 1, step: 1 },renderLayer: { step: 1, enumSource: "sortingLayers" },@@ -930,6 +938,10 @@ export interface SpriteData {export interface TilemapLayerData {cellSize: Vec2;+ orientation: number;+ hexSideLength: number;+ staggerAxis: number;+ staggerIndex: number;originOffset: Vec2;tileset: number;tilesetColumns: number;diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex d1ee59ef1..680c11941 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -404,6 +404,12 @@ export {decodeTilemapChunks,CHUNK_SIZE,tileCollisionOutlines,+ tileCellCenter,+ tileCellOutline,+ isNonOrthogonal,+ usesStagger,+ isHexOrientation,+ TileOrientation,TB_N,TB_E,TB_S,@@ -454,6 +460,8 @@ export {type TilesetModel,type DecodedChunk,type TileCollisionPiece,+ type TileGridParams,+ type Vec2Like,type TilesetAnimFrame,type TerrainMode,type TilesetTerrain,diff --git a/sdk/src/ecs/ptrAccessors.generated.ts b/sdk/src/ecs/ptrAccessors.generated.tsindex 5f9bd5eb2..a47620656 100644--- a/sdk/src/ecs/ptrAccessors.generated.ts+++ b/sdk/src/ecs/ptrAccessors.generated.ts@@ -1027,6 +1027,10 @@ export function createSpriteData(): SpritePtrData {export interface TilemapLayerPtrData {cellSize: Vec2;+ orientation: number;+ hexSideLength: number;+ staggerAxis: number;+ staggerIndex: number;originOffset: Vec2;tileset: number;tilesetColumns: number;@@ -1043,15 +1047,19 @@ export function fillTilemapLayer(ptr: number, out: TilemapLayerPtrData,): void {const cellSize_ = out.cellSize; cellSize_.x = f32[ptr >> 2]; cellSize_.y = f32[(ptr >> 2) + 1];- const originOffset_ = out.originOffset; originOffset_.x = f32[(ptr + 8) >> 2]; originOffset_.y = f32[((ptr + 8) >> 2) + 1];- out.tileset = u32[(ptr + 16) >> 2];- out.tilesetColumns = u32[(ptr + 20) >> 2] | 0;- out.tilesetRows = u32[(ptr + 24) >> 2] | 0;- out.renderLayer = u32[(ptr + 28) >> 2] | 0;- const tintColor_ = out.tintColor; tintColor_.r = f32[(ptr + 32) >> 2]; tintColor_.g = f32[((ptr + 32) >> 2) + 1]; tintColor_.b = f32[((ptr + 32) >> 2) + 2]; tintColor_.a = f32[((ptr + 32) >> 2) + 3];- out.opacity = f32[(ptr + 48) >> 2];- const parallaxFactor_ = out.parallaxFactor; parallaxFactor_.x = f32[(ptr + 52) >> 2]; parallaxFactor_.y = f32[((ptr + 52) >> 2) + 1];- out.visible = u8[ptr + 60] !== 0;+ out.orientation = u8[ptr + 8];+ out.hexSideLength = f32[(ptr + 12) >> 2];+ out.staggerAxis = u8[ptr + 16];+ out.staggerIndex = u8[ptr + 17];+ const originOffset_ = out.originOffset; originOffset_.x = f32[(ptr + 20) >> 2]; originOffset_.y = f32[((ptr + 20) >> 2) + 1];+ out.tileset = u32[(ptr + 28) >> 2];+ out.tilesetColumns = u32[(ptr + 32) >> 2] | 0;+ out.tilesetRows = u32[(ptr + 36) >> 2] | 0;+ out.renderLayer = u32[(ptr + 40) >> 2] | 0;+ const tintColor_ = out.tintColor; tintColor_.r = f32[(ptr + 44) >> 2]; tintColor_.g = f32[((ptr + 44) >> 2) + 1]; tintColor_.b = f32[((ptr + 44) >> 2) + 2]; tintColor_.a = f32[((ptr + 44) >> 2) + 3];+ out.opacity = f32[(ptr + 60) >> 2];+ const parallaxFactor_ = out.parallaxFactor; parallaxFactor_.x = f32[(ptr + 64) >> 2]; parallaxFactor_.y = f32[((ptr + 64) >> 2) + 1];+ out.visible = u8[ptr + 72] !== 0;}export function writeTilemapLayer(@@ -1059,20 +1067,28 @@ export function writeTilemapLayer(ptr: number, data: TilemapLayerPtrData,): void {f32[ptr >> 2] = data.cellSize.x; f32[(ptr >> 2) + 1] = data.cellSize.y;- f32[(ptr + 8) >> 2] = data.originOffset.x; f32[((ptr + 8) >> 2) + 1] = data.originOffset.y;- u32[(ptr + 16) >> 2] = data.tileset;- u32[(ptr + 20) >> 2] = data.tilesetColumns | 0;- u32[(ptr + 24) >> 2] = data.tilesetRows | 0;- u32[(ptr + 28) >> 2] = data.renderLayer | 0;- f32[(ptr + 32) >> 2] = data.tintColor.r; f32[((ptr + 32) >> 2) + 1] = data.tintColor.g; f32[((ptr + 32) >> 2) + 2] = data.tintColor.b; f32[((ptr + 32) >> 2) + 3] = data.tintColor.a;- f32[(ptr + 48) >> 2] = data.opacity;- f32[(ptr + 52) >> 2] = data.parallaxFactor.x; f32[((ptr + 52) >> 2) + 1] = data.parallaxFactor.y;- u8[ptr + 60] = data.visible ? 1 : 0;+ u8[ptr + 8] = data.orientation;+ f32[(ptr + 12) >> 2] = data.hexSideLength;+ u8[ptr + 16] = data.staggerAxis;+ u8[ptr + 17] = data.staggerIndex;+ f32[(ptr + 20) >> 2] = data.originOffset.x; f32[((ptr + 20) >> 2) + 1] = data.originOffset.y;+ u32[(ptr + 28) >> 2] = data.tileset;+ u32[(ptr + 32) >> 2] = data.tilesetColumns | 0;+ u32[(ptr + 36) >> 2] = data.tilesetRows | 0;+ u32[(ptr + 40) >> 2] = data.renderLayer | 0;+ f32[(ptr + 44) >> 2] = data.tintColor.r; f32[((ptr + 44) >> 2) + 1] = data.tintColor.g; f32[((ptr + 44) >> 2) + 2] = data.tintColor.b; f32[((ptr + 44) >> 2) + 3] = data.tintColor.a;+ f32[(ptr + 60) >> 2] = data.opacity;+ f32[(ptr + 64) >> 2] = data.parallaxFactor.x; f32[((ptr + 64) >> 2) + 1] = data.parallaxFactor.y;+ u8[ptr + 72] = data.visible ? 1 : 0;}export function createTilemapLayerData(): TilemapLayerPtrData {return {cellSize: { x: 0, y: 0 },+ orientation: 0,+ hexSideLength: 0,+ staggerAxis: 0,+ staggerIndex: 0,originOffset: { x: 0, y: 0 },tileset: 0,tilesetColumns: 0,diff --git a/sdk/src/ptrLayouts.generated.ts b/sdk/src/ptrLayouts.generated.tsindex 5c47efd41..13a6eeead 100644--- a/sdk/src/ptrLayouts.generated.ts+++ b/sdk/src/ptrLayouts.generated.ts@@ -276,15 +276,19 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {ptrFn: 'getTilemapLayerPtr',fields: [{ name: 'cellSize', type: 'vec2', offset: 0 },- { name: 'originOffset', type: 'vec2', offset: 8 },- { name: 'tileset', type: 'u32', offset: 16 },- { name: 'tilesetColumns', type: 'i32', offset: 20 },- { name: 'tilesetRows', type: 'i32', offset: 24 },- { name: 'renderLayer', type: 'i32', offset: 28 },- { name: 'tintColor', type: 'color', offset: 32 },- { name: 'opacity', type: 'f32', offset: 48 },- { name: 'parallaxFactor', type: 'vec2', offset: 52 },- { name: 'visible', type: 'bool', offset: 60 },+ { name: 'orientation', type: 'u8', offset: 8 },+ { name: 'hexSideLength', type: 'f32', offset: 12 },+ { name: 'staggerAxis', type: 'u8', offset: 16 },+ { name: 'staggerIndex', type: 'u8', offset: 17 },+ { name: 'originOffset', type: 'vec2', offset: 20 },+ { name: 'tileset', type: 'u32', offset: 28 },+ { name: 'tilesetColumns', type: 'i32', offset: 32 },+ { name: 'tilesetRows', type: 'i32', offset: 36 },+ { name: 'renderLayer', type: 'i32', offset: 40 },+ { name: 'tintColor', type: 'color', offset: 44 },+ { name: 'opacity', type: 'f32', offset: 60 },+ { name: 'parallaxFactor', type: 'vec2', offset: 64 },+ { name: 'visible', type: 'bool', offset: 72 },],},TrailRenderer: {diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.tsindex 9fac83d85..c49dd7ffa 100644--- a/sdk/src/tilemap/index.ts+++ b/sdk/src/tilemap/index.ts@@ -16,6 +16,10 @@ export {type TiledAnimFrame, type TilemapLoadOptions,} from './tiledLoader';export { tileCollisionOutlines, type TileCollisionPiece } from './tileCollisionOutline';+export {+ tileCellCenter, tileCellOutline, isNonOrthogonal, usesStagger, isHexOrientation, TileOrientation,+ type TileGridParams, type Vec2Like,+} from './tileGeometry';export { mergeCollisionTiles, type MergedRect } from './collisionMerge';export { decodeTilemapChunks, CHUNK_SIZE, type DecodedChunk } from './chunkCodec';export {diff --git a/sdk/src/tilemap/tileGeometry.ts b/sdk/src/tilemap/tileGeometry.tsnew file mode 100644index 000000000..fbfc5eef1--- /dev/null+++ b/sdk/src/tilemap/tileGeometry.ts@@ -0,0 +1,129 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file tileGeometry.ts+ * @brief Orientation-aware tile-cell geometry — the single TS mirror of the C+++ * placement math in TilemapRenderPlugin / TilemapSystem.+ *+ * The renderer always draws a tile as an axis-aligned tileWidth×tileHeight quad;+ * only its CENTER moves per orientation (orthogonal / isometric / staggered /+ * hexagonal). {@link tileCellCenter} reproduces that center (layer-local, y-up —+ * the caller adds the layer's world origin), so the editor brush ghost lands+ * exactly where the runtime will draw the tile.+ *+ * The CELL itself is a rect (orthogonal), a diamond (isometric / staggered), or a+ * hexagon (hexagonal). {@link tileCellOutline} returns that polygon as offsets+ * around the center — the same shape for every cell — so the editor grid overlay+ * and shaped ghost draw the true cell boundary. One geometry seam drives both.+ */++/** Grid orientation, values matching the C++ TilemapOrientation / tilemap::GridType. */+export enum TileOrientation {+ Orthogonal = 0,+ Isometric = 1,+ Staggered = 2,+ Hexagonal = 3,+}++/** The layout inputs a cell placement needs — a subset of the TilemapLayer component. */+export interface TileGridParams {+ /** 0 orthogonal · 1 isometric · 2 staggered · 3 hexagonal. */+ orientation: number;+ tileWidth: number;+ tileHeight: number;+ /** Hex edge length in px along the stagger axis (0 → tileHeight/2). Hex only. */+ hexSideLength?: number;+ /** staggerAxis === X: columns stagger (else rows). Staggered + hex. */+ staggerAxisX?: boolean;+ /** staggerIndex === Even carries the half-cell shift (else odd). Staggered + hex. */+ staggerIndexEven?: boolean;+}++export interface Vec2Like {+ x: number;+ y: number;+}++/** The effective hex side length: the authored value, or the regular-hex fallback (th/2). */+function hexSide(p: TileGridParams): number {+ return p.hexSideLength && p.hexSideLength > 0 ? p.hexSideLength : p.tileHeight * 0.5;+}++/**+ * The center of cell (tx, ty) in the layer's local space (y-up, layer origin at 0,0).+ * Add the layer entity's world position to get world coords. Mirrors the C++ renderer's+ * `(worldX, worldY)` per-tile center exactly, so a painted map and an imported one place+ * a given cell at the same point.+ */+export function tileCellCenter(p: TileGridParams, tx: number, ty: number): Vec2Like {+ const hw = p.tileWidth * 0.5;+ const hh = p.tileHeight * 0.5;+ switch (p.orientation) {+ case TileOrientation.Isometric:+ return { x: (tx - ty) * hw, y: -(tx + ty) * hh };+ case TileOrientation.Staggered:+ case TileOrientation.Hexagonal: {+ const side = p.orientation === TileOrientation.Hexagonal ? hexSide(p) : 0;+ if (p.staggerAxisX) {+ const colW = (p.tileWidth + side) * 0.5;+ const staggered = ((tx & 1) !== 0) !== !!p.staggerIndexEven;+ return { x: tx * colW + hw, y: -(ty * p.tileHeight + (staggered ? hh : 0) + hh) };+ }+ const rowH = (p.tileHeight + side) * 0.5;+ const staggered = ((ty & 1) !== 0) !== !!p.staggerIndexEven;+ return { x: tx * p.tileWidth + (staggered ? hw : 0) + hw, y: -(ty * rowH + hh) };+ }+ default: // Orthogonal+ return { x: tx * p.tileWidth + hw, y: -(ty * p.tileHeight + hh) };+ }+}++/**+ * The cell outline as offsets around its center (y-up, world units) — the same polygon+ * for every cell of a given layout. Rect (orthogonal), diamond inscribed in the tile box+ * (isometric / staggered), or a Tiled hexagon whose flat edges (length = side) run along+ * the stagger axis (hexagonal). Draw it translated to each {@link tileCellCenter}.+ */+export function tileCellOutline(p: TileGridParams): Vec2Like[] {+ const hw = p.tileWidth * 0.5;+ const hh = p.tileHeight * 0.5;+ switch (p.orientation) {+ case TileOrientation.Isometric:+ case TileOrientation.Staggered:+ // Diamond: top, right, bottom, left.+ return [{ x: 0, y: hh }, { x: hw, y: 0 }, { x: 0, y: -hh }, { x: -hw, y: 0 }];+ case TileOrientation.Hexagonal: {+ const s = Math.min(hexSide(p), p.tileHeight, p.tileWidth); // clamp so it stays inside the box+ const hs = s * 0.5;+ if (p.staggerAxisX) {+ // Flat-top hex: horizontal flat edges (length s) top and bottom, points left/right.+ return [+ { x: -hs, y: hh }, { x: hs, y: hh }, { x: hw, y: 0 },+ { x: hs, y: -hh }, { x: -hs, y: -hh }, { x: -hw, y: 0 },+ ];+ }+ // Pointy-top hex: vertical flat edges (length s) left and right, points top/bottom.+ return [+ { x: 0, y: hh }, { x: hw, y: hs }, { x: hw, y: -hs },+ { x: 0, y: -hh }, { x: -hw, y: -hs }, { x: -hw, y: hs },+ ];+ }+ default: // Orthogonal rect: tl, tr, br, bl (y-up).+ return [{ x: -hw, y: hh }, { x: hw, y: hh }, { x: hw, y: -hh }, { x: -hw, y: -hh }];+ }+}++/** True when the layout is anything other than a plain orthogonal square grid. */+export function isNonOrthogonal(orientation: number): boolean {+ return orientation !== TileOrientation.Orthogonal && orientation !== undefined;+}++/** True for the layouts that read the stagger axis/index (staggered + hexagonal). */+export function usesStagger(orientation: number): boolean {+ return orientation === TileOrientation.Staggered || orientation === TileOrientation.Hexagonal;+}++/** True for the hexagonal layout (the only one that reads the hex side length). */+export function isHexOrientation(orientation: number): boolean {+ return orientation === TileOrientation.Hexagonal;+}diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.tsindex 81e248dce..d0d8c0d6a 100644--- a/sdk/src/tilemap/tilemapPlugin.ts+++ b/sdk/src/tilemap/tilemapPlugin.ts@@ -31,6 +31,7 @@ const GRID_TYPE_MAP: Record<string, number> = {staggered: 2,hexagonal: 3,};+const GRID_STAGGERED = 2;const GRID_HEXAGONAL = 3;export class TilemapPlugin implements Plugin {@@ -42,6 +43,11 @@ export class TilemapPlugin implements Plugin {* is the authority, so an edit must re-push — otherwise the paint grid (cellSize)* and the drawn/hit grid (stale tile_width) diverge and tiles land off-cursor. */private appliedCellSize_ = new Map<number, number>();+ /** TilemapLayer entity → the grid params last pushed (orientation|side|axis|index).+ * Grid type + stagger/hex params live in the C++ LayerData; the component is the+ * authority, so an orientation edit (or a cellSize re-init, which resets LayerData)+ * must re-push — otherwise the drawn/hit grid diverges from the authored one. */+ private appliedGrid_ = new Map<number, string>();private animatedLayers_ = new Set<number>();/** Tilemap(source) entity → the RuntimeOnly child layer entities derived from its `.tmj`. */private sourceLayerEntities_ = new Map<number, Entity[]>();@@ -159,6 +165,7 @@ export class TilemapPlugin implements Plugin {const world = app.world;const initializedLayers = this.initializedLayers_;const appliedCellSize = this.appliedCellSize_;+ const appliedGrid = this.appliedGrid_;const animatedLayers = this.animatedLayers_;const sourceLayerEntities = this.sourceLayerEntities_;const collisionEntities = this.collisionEntities_;@@ -197,6 +204,7 @@ export class TilemapPlugin implements Plugin {TilemapAPI.destroyLayer(entity);initializedLayers.delete(entity);appliedCellSize.delete(entity);+ appliedGrid.delete(entity);nativeCollisionIds.delete(entity);nativeTileShapes.delete(entity);tilesetRefs.delete(entity);@@ -229,6 +237,7 @@ export class TilemapPlugin implements Plugin {// whenever the applied size drifts. Stale dims misplace every tile// relative to the paint grid (renderer + worldToTile read tile_width).const csKey = layerData.cellSize.x * 65536 + layerData.cellSize.y;+ let reinit = false;if (!initializedLayers.has(entity)) {TilemapAPI.initInfiniteLayer(entity, layerData.cellSize.x, layerData.cellSize.y,@@ -236,11 +245,30 @@ export class TilemapPlugin implements Plugin {TilemapAPI.setOriginEntity(entity, entity);initializedLayers.add(entity);appliedCellSize.set(entity, csKey);+ reinit = true;} else if (appliedCellSize.get(entity) !== csKey) {TilemapAPI.initInfiniteLayer(entity, layerData.cellSize.x, layerData.cellSize.y,);appliedCellSize.set(entity, csKey);+ reinit = true;+ }++ // Grid orientation + stagger/hex params from the component (the+ // authority): push on an orientation edit, or after a (re)init that+ // reset the C++ LayerData grid state. Staggered (2) and hexagonal (3)+ // both read the stagger axis/index; orthogonal/isometric ignore them.+ // Same worldToTile/renderer path the imported .tmj layers use, so a+ // painted iso/hex map places tiles exactly like an imported one.+ const gridKey = `${layerData.orientation ?? 0}|${layerData.hexSideLength ?? 0}`+ + `|${layerData.staggerAxis ?? 0}|${layerData.staggerIndex ?? 0}`;+ if (reinit || appliedGrid.get(entity) !== gridKey) {+ TilemapAPI.setGridType(entity, layerData.orientation ?? 0);+ TilemapAPI.setHexParams(+ entity, layerData.hexSideLength ?? 0,+ (layerData.staggerAxis ?? 0) === 1, (layerData.staggerIndex ?? 0) === 1,+ );+ appliedGrid.set(entity, gridKey);}// Live tileset(s): when ALL the layer's `.estileset` refs have loaded,@@ -378,7 +406,9 @@ export class TilemapPlugin implements Plugin {if (gridType !== 0) {TilemapAPI.setGridType(child, gridType);}- if (gridType === GRID_HEXAGONAL) {+ // Staggered + hexagonal both read the stagger axis/index (the+ // half-cell shift). Staggered iso ignores the side length.+ if (gridType === GRID_STAGGERED || gridType === GRID_HEXAGONAL) {TilemapAPI.setHexParams(child, cached.hexSideLength ?? 0,cached.staggerAxis === 'x', cached.staggerIndex === 'even',diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.tsindex 2c96ec410..28f4fd4da 100644--- a/sdk/src/wasm.generated.ts+++ b/sdk/src/wasm.generated.ts@@ -137,6 +137,23 @@ export enum TextAlign {Right = 2,}+export enum TilemapOrientation {+ Orthogonal = 0,+ Isometric = 1,+ Staggered = 2,+ Hexagonal = 3,+}++export enum TilemapStaggerAxis {+ Y = 0,+ X = 1,+}++export enum TilemapStaggerIndex {+ Odd = 0,+ Even = 1,+}+export enum UIDisplay {Flex = 0,None = 1,@@ -409,6 +426,10 @@ export interface Sprite {export interface TilemapLayer {cellSize: Vec2;+ orientation: number;+ hexSideLength: number;+ staggerAxis: number;+ staggerIndex: number;originOffset: Vec2;tileset: number;tilesetColumns: number;diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex edc46c256..d445e742d 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -529,16 +529,68 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho},},"TilemapLayer": {+ "hexSideLength": {+ "min": 0,+ "step": 1,+ "tooltip": "Hexagonal side length in px (0 = a regular pointy hex = tileHeight/2). Ignored unless orientation is Hexagonal.",+ },"opacity": {"max": 1,"min": 0,"slider": true,"tooltip": "Layer transparency (0 = invisible, 1 = opaque).",},+ "orientation": {+ "enum": [+ {+ "label": "Orthogonal",+ "value": 0,+ },+ {+ "label": "Isometric",+ "value": 1,+ },+ {+ "label": "Staggered",+ "value": 2,+ },+ {+ "label": "Hexagonal",+ "value": 3,+ },+ ],+ "tooltip": "Grid layout: orthogonal, isometric, staggered, or hexagonal.",+ },"renderLayer": {"enumSource": "sortingLayers","step": 1,},+ "staggerAxis": {+ "enum": [+ {+ "label": "Y",+ "value": 0,+ },+ {+ "label": "X",+ "value": 1,+ },+ ],+ "tooltip": "Stagger axis (staggered/hex): Y shifts rows, X shifts columns.",+ },+ "staggerIndex": {+ "enum": [+ {+ "label": "Odd",+ "value": 0,+ },+ {+ "label": "Even",+ "value": 1,+ },+ ],+ "tooltip": "Which lines carry the half-cell shift (staggered/hex).",+ },"tilesetColumns": {"min": 1,"step": 1,diff --git a/sdk/tests/tileGeometry.test.ts b/sdk/tests/tileGeometry.test.tsnew file mode 100644index 000000000..ce1e652a9--- /dev/null+++ b/sdk/tests/tileGeometry.test.ts@@ -0,0 +1,121 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import {+ tileCellCenter, tileCellOutline, isNonOrthogonal, TileOrientation,+ type TileGridParams,+} from '../src/tilemap/tileGeometry';++// tw=64, th=32 so hw=32, hh=16 — a rectangular tile that makes iso/hex offsets legible.+const base = { tileWidth: 64, tileHeight: 32 };+const close = (a: number, b: number) => expect(a).toBeCloseTo(b, 5);+const centerEq = (p: TileGridParams, tx: number, ty: number, x: number, y: number) => {+ const c = tileCellCenter(p, tx, ty);+ close(c.x, x); close(c.y, y);+};++describe('tileCellCenter', () => {+ it('orthogonal: tile (0,0) center sits at (+hw,-hh); +tx→right, +ty→down', () => {+ const p = { ...base, orientation: TileOrientation.Orthogonal };+ centerEq(p, 0, 0, 32, -16);+ centerEq(p, 1, 0, 96, -16);+ centerEq(p, 0, 1, 32, -48);+ });++ it('isometric: tile (0,0) center is the origin; the lattice is a diamond', () => {+ const p = { ...base, orientation: TileOrientation.Isometric };+ centerEq(p, 0, 0, 0, 0);+ centerEq(p, 1, 0, 32, -16);+ centerEq(p, 0, 1, -32, -16);+ centerEq(p, 1, 1, 0, -32);+ });++ it('staggered (axis Y, index odd): odd rows shift right hw and every row drops hh', () => {+ const p = { ...base, orientation: TileOrientation.Staggered };+ centerEq(p, 0, 0, 32, -16);+ centerEq(p, 0, 1, 64, -32); // row 1 (odd) shifted +hw, dropped +hh+ centerEq(p, 0, 2, 32, -48); // row 2 (even) back to the column+ });++ it('staggered index even flips which rows shift', () => {+ const p = { ...base, orientation: TileOrientation.Staggered, staggerIndexEven: true };+ centerEq(p, 0, 0, 64, -16); // row 0 (even) now shifted+ centerEq(p, 0, 1, 32, -32); // row 1 (odd) unshifted+ });++ it('staggered axis X shifts odd columns down instead of rows right', () => {+ const p = { ...base, orientation: TileOrientation.Staggered, staggerAxisX: true };+ // colW = (64+0)/2 = 32+ centerEq(p, 0, 0, 32, -16);+ centerEq(p, 1, 0, 64, -32); // col 1 (odd) shifted down hh, advanced one colW+ centerEq(p, 2, 0, 96, -16);+ });++ it('hexagonal (axis Y): row pitch is (th+side)/2, side defaults to th/2', () => {+ const side8 = { ...base, orientation: TileOrientation.Hexagonal, hexSideLength: 8 };+ // rowH = (32+8)/2 = 20+ centerEq(side8, 0, 0, 32, -16);+ centerEq(side8, 0, 1, 64, -36); // odd row shifted +hw, y = -(20 + 16)+ centerEq(side8, 0, 2, 32, -56); // even row, y = -(40 + 16)++ const dflt = { ...base, orientation: TileOrientation.Hexagonal }; // side → th/2 = 16+ // rowH = (32+16)/2 = 24+ centerEq(dflt, 0, 2, 32, -64); // y = -(2*24 + 16)+ });++ it('hexagonal axis X: column pitch is (tw+side)/2', () => {+ const p = { ...base, orientation: TileOrientation.Hexagonal, hexSideLength: 8, staggerAxisX: true };+ // colW = (64+8)/2 = 36+ centerEq(p, 0, 0, 32, -16);+ centerEq(p, 1, 0, 68, -32); // col 1 (odd) shifted down hh, x = 36 + 32+ centerEq(p, 2, 0, 104, -16);+ });+});++describe('tileCellOutline', () => {+ it('orthogonal outline is the tile rect', () => {+ const o = tileCellOutline({ ...base, orientation: TileOrientation.Orthogonal });+ expect(o).toHaveLength(4);+ // spans the full tile box+ expect(Math.max(...o.map((v) => v.x))).toBe(32);+ expect(Math.min(...o.map((v) => v.x))).toBe(-32);+ expect(Math.max(...o.map((v) => v.y))).toBe(16);+ });++ it('isometric/staggered outline is a diamond (points on the axes)', () => {+ for (const orientation of [TileOrientation.Isometric, TileOrientation.Staggered]) {+ const o = tileCellOutline({ ...base, orientation });+ expect(o).toEqual([{ x: 0, y: 16 }, { x: 32, y: 0 }, { x: 0, y: -16 }, { x: -32, y: 0 }]);+ }+ });++ it('hexagonal axis Y is a pointy-top hex: 6 verts, flat edges vertical of length side', () => {+ const o = tileCellOutline({ ...base, orientation: TileOrientation.Hexagonal, hexSideLength: 8 });+ expect(o).toHaveLength(6);+ // top and bottom are single points on the y axis+ expect(o).toContainEqual({ x: 0, y: 16 });+ expect(o).toContainEqual({ x: 0, y: -16 });+ // right flat edge: two verts at x=+hw, y=±side/2+ expect(o).toContainEqual({ x: 32, y: 4 });+ expect(o).toContainEqual({ x: 32, y: -4 });+ });++ it('hexagonal axis X is a flat-top hex: points on the x axis', () => {+ const o = tileCellOutline({ ...base, orientation: TileOrientation.Hexagonal, hexSideLength: 8, staggerAxisX: true });+ expect(o).toHaveLength(6);+ expect(o).toContainEqual({ x: 32, y: 0 });+ expect(o).toContainEqual({ x: -32, y: 0 });+ // top flat edge (length side) at y=+hh+ expect(o).toContainEqual({ x: -4, y: 16 });+ expect(o).toContainEqual({ x: 4, y: 16 });+ });+});++describe('isNonOrthogonal', () => {+ it('is true for iso/staggered/hex, false for orthogonal', () => {+ expect(isNonOrthogonal(TileOrientation.Orthogonal)).toBe(false);+ expect(isNonOrthogonal(TileOrientation.Isometric)).toBe(true);+ expect(isNonOrthogonal(TileOrientation.Staggered)).toBe(true);+ expect(isNonOrthogonal(TileOrientation.Hexagonal)).toBe(true);+ });+});diff --git a/sdk/tests/tilemap.test.ts b/sdk/tests/tilemap.test.tsindex 525bb2ac5..6f25925e4 100644--- a/sdk/tests/tilemap.test.ts+++ b/sdk/tests/tilemap.test.ts@@ -76,6 +76,10 @@ describe('Tilemap Components', () => {it('should have correct defaults', () => {expect(TilemapLayer._default).toEqual({cellSize: { x: 32, y: 32 },+ orientation: 0,+ hexSideLength: 0,+ staggerAxis: 0,+ staggerIndex: 0,originOffset: { x: 0, y: 0 },tileset: 0,tilesetColumns: 1,diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex 3e3ea62a5..4bf0629db 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash 1f7fbdd80441c044+ * @schema_hash 2544ca6f23aa33a5*/-#define ES_EDITOR_API_SCHEMA_HASH "1f7fbdd80441c044"+#define ES_EDITOR_API_SCHEMA_HASH "2544ca6f23aa33a5"#include <emscripten/bind.h>#include <string>@@ -380,6 +380,10 @@ std::string editor_getComponentSchema(const std::string& name) {return R"JSON([{"key":"cellSize.x","type":"float","group":"TilemapLayer"},{"key":"cellSize.y","type":"float","group":"TilemapLayer"},+ {"key":"orientation","type":"int","group":"TilemapLayer"},+ {"key":"hexSideLength","type":"float","group":"TilemapLayer"},+ {"key":"staggerAxis","type":"int","group":"TilemapLayer"},+ {"key":"staggerIndex","type":"int","group":"TilemapLayer"},{"key":"originOffset.x","type":"float","group":"TilemapLayer"},{"key":"originOffset.y","type":"float","group":"TilemapLayer"},{"key":"tileset","type":"asset","group":"TilemapLayer"},@@ -970,6 +974,7 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::sauto& c = reg.get<esengine::ecs::TilemapLayer>(entity);if (field == "cellSize.x") { c.cellSize.x = value; }else if (field == "cellSize.y") { c.cellSize.y = value; }+ else if (field == "hexSideLength") { c.hexSideLength = value; }else if (field == "originOffset.x") { c.originOffset.x = value; }else if (field == "originOffset.y") { c.originOffset.y = value; }else if (field == "tintColor.r") { c.tintColor.r = value; }@@ -1299,6 +1304,7 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::stconst auto& c = reg.get<esengine::ecs::TilemapLayer>(entity);if (field == "cellSize.x") { return c.cellSize.x; }else if (field == "cellSize.y") { return c.cellSize.y; }+ else if (field == "hexSideLength") { return c.hexSideLength; }else if (field == "originOffset.x") { return c.originOffset.x; }else if (field == "originOffset.y") { return c.originOffset.y; }else if (field == "tintColor.r") { return c.tintColor.r; }@@ -1534,7 +1540,10 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str} else if (comp == "TilemapLayer") {if (!reg.has<esengine::ecs::TilemapLayer>(entity)) return false;auto& c = reg.get<esengine::ecs::TilemapLayer>(entity);- if (field == "tileset") { c.tileset = resource::TextureHandle(static_cast<u32>(value)); }+ if (field == "orientation") { c.orientation = static_cast<u8>(value); }+ else if (field == "staggerAxis") { c.staggerAxis = static_cast<u8>(value); }+ else if (field == "staggerIndex") { c.staggerIndex = static_cast<u8>(value); }+ else if (field == "tileset") { c.tileset = resource::TextureHandle(static_cast<u32>(value)); }else if (field == "tilesetColumns") { c.tilesetColumns = static_cast<i32>(value); }else if (field == "tilesetRows") { c.tilesetRows = static_cast<i32>(value); }else if (field == "renderLayer") { c.renderLayer = static_cast<i32>(value); }@@ -1678,7 +1687,10 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri} else if (comp == "TilemapLayer") {if (!reg.has<esengine::ecs::TilemapLayer>(entity)) return 0;const auto& c = reg.get<esengine::ecs::TilemapLayer>(entity);- if (field == "tileset") { return static_cast<i32>(c.tileset.id()); }+ if (field == "orientation") { return static_cast<i32>(c.orientation); }+ else if (field == "staggerAxis") { return static_cast<i32>(c.staggerAxis); }+ else if (field == "staggerIndex") { return static_cast<i32>(c.staggerIndex); }+ else if (field == "tileset") { return static_cast<i32>(c.tileset.id()); }else if (field == "tilesetColumns") { return static_cast<i32>(c.tilesetColumns); }else if (field == "tilesetRows") { return static_cast<i32>(c.tilesetRows); }else if (field == "renderLayer") { return static_cast<i32>(c.renderLayer); }diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex fb43236cc..55619359c 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -182,6 +182,20 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {.value("Center", esengine::ecs::TextAlign::Center).value("Right", esengine::ecs::TextAlign::Right);+ enum_<esengine::ecs::TilemapOrientation>("TilemapOrientation")+ .value("Orthogonal", esengine::ecs::TilemapOrientation::Orthogonal)+ .value("Isometric", esengine::ecs::TilemapOrientation::Isometric)+ .value("Staggered", esengine::ecs::TilemapOrientation::Staggered)+ .value("Hexagonal", esengine::ecs::TilemapOrientation::Hexagonal);++ enum_<esengine::ecs::TilemapStaggerAxis>("TilemapStaggerAxis")+ .value("Y", esengine::ecs::TilemapStaggerAxis::Y)+ .value("X", esengine::ecs::TilemapStaggerAxis::X);++ enum_<esengine::ecs::TilemapStaggerIndex>("TilemapStaggerIndex")+ .value("Odd", esengine::ecs::TilemapStaggerIndex::Odd)+ .value("Even", esengine::ecs::TilemapStaggerIndex::Even);+enum_<esengine::ecs::UIDisplay>("UIDisplay").value("Flex", esengine::ecs::UIDisplay::Flex).value("None", esengine::ecs::UIDisplay::None);@@ -663,6 +677,10 @@ SpriteJS spriteToJS(const esengine::ecs::Sprite& c) {struct TilemapLayerJS {glm::vec2 cellSize;+ u8 orientation;+ f32 hexSideLength;+ u8 staggerAxis;+ u8 staggerIndex;glm::vec2 originOffset;u32 tileset;i32 tilesetColumns;@@ -677,6 +695,10 @@ struct TilemapLayerJS {esengine::ecs::TilemapLayer tilemaplayerFromJS(const TilemapLayerJS& js) {esengine::ecs::TilemapLayer c;c.cellSize = js.cellSize;+ c.orientation = js.orientation;+ c.hexSideLength = js.hexSideLength;+ c.staggerAxis = js.staggerAxis;+ c.staggerIndex = js.staggerIndex;c.originOffset = js.originOffset;c.tileset = resource::TextureHandle(js.tileset);c.tilesetColumns = js.tilesetColumns;@@ -692,6 +714,10 @@ esengine::ecs::TilemapLayer tilemaplayerFromJS(const TilemapLayerJS& js) {TilemapLayerJS tilemaplayerToJS(const esengine::ecs::TilemapLayer& c) {TilemapLayerJS js;js.cellSize = c.cellSize;+ js.orientation = c.orientation;+ js.hexSideLength = c.hexSideLength;+ js.staggerAxis = c.staggerAxis;+ js.staggerIndex = c.staggerIndex;js.originOffset = c.originOffset;js.tileset = c.tileset.id();js.tilesetColumns = c.tilesetColumns;@@ -1114,6 +1140,10 @@ EMSCRIPTEN_BINDINGS(esengine_components) {value_object<TilemapLayerJS>("TilemapLayer").field("cellSize", &TilemapLayerJS::cellSize)+ .field("orientation", &TilemapLayerJS::orientation)+ .field("hexSideLength", &TilemapLayerJS::hexSideLength)+ .field("staggerAxis", &TilemapLayerJS::staggerAxis)+ .field("staggerIndex", &TilemapLayerJS::staggerIndex).field("originOffset", &TilemapLayerJS::originOffset).field("tileset", &TilemapLayerJS::tileset).field("tilesetColumns", &TilemapLayerJS::tilesetColumns)@@ -1997,15 +2027,19 @@ static_assert(offsetof(esengine::ecs::Sprite, parallax) == 76, "ABI offset driftstatic_assert(offsetof(esengine::ecs::Sprite, material) == 84, "ABI offset drift: esengine::ecs::Sprite.material (EHT expected 84)");static_assert(offsetof(esengine::ecs::Sprite, enabled) == 88, "ABI offset drift: esengine::ecs::Sprite.enabled (EHT expected 88)");static_assert(offsetof(esengine::ecs::TilemapLayer, cellSize) == 0, "ABI offset drift: esengine::ecs::TilemapLayer.cellSize (EHT expected 0)");-static_assert(offsetof(esengine::ecs::TilemapLayer, originOffset) == 8, "ABI offset drift: esengine::ecs::TilemapLayer.originOffset (EHT expected 8)");-static_assert(offsetof(esengine::ecs::TilemapLayer, tileset) == 16, "ABI offset drift: esengine::ecs::TilemapLayer.tileset (EHT expected 16)");-static_assert(offsetof(esengine::ecs::TilemapLayer, tilesetColumns) == 20, "ABI offset drift: esengine::ecs::TilemapLayer.tilesetColumns (EHT expected 20)");-static_assert(offsetof(esengine::ecs::TilemapLayer, tilesetRows) == 24, "ABI offset drift: esengine::ecs::TilemapLayer.tilesetRows (EHT expected 24)");-static_assert(offsetof(esengine::ecs::TilemapLayer, renderLayer) == 28, "ABI offset drift: esengine::ecs::TilemapLayer.renderLayer (EHT expected 28)");-static_assert(offsetof(esengine::ecs::TilemapLayer, tintColor) == 32, "ABI offset drift: esengine::ecs::TilemapLayer.tintColor (EHT expected 32)");-static_assert(offsetof(esengine::ecs::TilemapLayer, opacity) == 48, "ABI offset drift: esengine::ecs::TilemapLayer.opacity (EHT expected 48)");-static_assert(offsetof(esengine::ecs::TilemapLayer, parallaxFactor) == 52, "ABI offset drift: esengine::ecs::TilemapLayer.parallaxFactor (EHT expected 52)");-static_assert(offsetof(esengine::ecs::TilemapLayer, visible) == 60, "ABI offset drift: esengine::ecs::TilemapLayer.visible (EHT expected 60)");+static_assert(offsetof(esengine::ecs::TilemapLayer, orientation) == 8, "ABI offset drift: esengine::ecs::TilemapLayer.orientation (EHT expected 8)");+static_assert(offsetof(esengine::ecs::TilemapLayer, hexSideLength) == 12, "ABI offset drift: esengine::ecs::TilemapLayer.hexSideLength (EHT expected 12)");+static_assert(offsetof(esengine::ecs::TilemapLayer, staggerAxis) == 16, "ABI offset drift: esengine::ecs::TilemapLayer.staggerAxis (EHT expected 16)");+static_assert(offsetof(esengine::ecs::TilemapLayer, staggerIndex) == 17, "ABI offset drift: esengine::ecs::TilemapLayer.staggerIndex (EHT expected 17)");+static_assert(offsetof(esengine::ecs::TilemapLayer, originOffset) == 20, "ABI offset drift: esengine::ecs::TilemapLayer.originOffset (EHT expected 20)");+static_assert(offsetof(esengine::ecs::TilemapLayer, tileset) == 28, "ABI offset drift: esengine::ecs::TilemapLayer.tileset (EHT expected 28)");+static_assert(offsetof(esengine::ecs::TilemapLayer, tilesetColumns) == 32, "ABI offset drift: esengine::ecs::TilemapLayer.tilesetColumns (EHT expected 32)");+static_assert(offsetof(esengine::ecs::TilemapLayer, tilesetRows) == 36, "ABI offset drift: esengine::ecs::TilemapLayer.tilesetRows (EHT expected 36)");+static_assert(offsetof(esengine::ecs::TilemapLayer, renderLayer) == 40, "ABI offset drift: esengine::ecs::TilemapLayer.renderLayer (EHT expected 40)");+static_assert(offsetof(esengine::ecs::TilemapLayer, tintColor) == 44, "ABI offset drift: esengine::ecs::TilemapLayer.tintColor (EHT expected 44)");+static_assert(offsetof(esengine::ecs::TilemapLayer, opacity) == 60, "ABI offset drift: esengine::ecs::TilemapLayer.opacity (EHT expected 60)");+static_assert(offsetof(esengine::ecs::TilemapLayer, parallaxFactor) == 64, "ABI offset drift: esengine::ecs::TilemapLayer.parallaxFactor (EHT expected 64)");+static_assert(offsetof(esengine::ecs::TilemapLayer, visible) == 72, "ABI offset drift: esengine::ecs::TilemapLayer.visible (EHT expected 72)");static_assert(offsetof(esengine::ecs::TrailRenderer, time) == 0, "ABI offset drift: esengine::ecs::TrailRenderer.time (EHT expected 0)");static_assert(offsetof(esengine::ecs::TrailRenderer, minVertexDistance) == 4, "ABI offset drift: esengine::ecs::TrailRenderer.minVertexDistance (EHT expected 4)");static_assert(offsetof(esengine::ecs::TrailRenderer, emitting) == 8, "ABI offset drift: esengine::ecs::TrailRenderer.emitting (EHT expected 8)");@@ -2055,7 +2089,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "bde213b560e9ce4c";+static const char* kEsAbiLayoutHash = "4e0613ea05e766a3";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/TilemapLayer.hpp b/src/esengine/ecs/components/TilemapLayer.hppindex 0eac1f8a7..860bab009 100644--- a/src/esengine/ecs/components/TilemapLayer.hpp+++ b/src/esengine/ecs/components/TilemapLayer.hpp@@ -13,6 +13,33 @@namespace esengine::ecs {+/**+ * Grid layout of a tilemap layer. Values match tilemap::GridType 1:1 so the+ * component field maps straight to the runtime grid type. "Staggered" is the+ * staggered-isometric grid; it and Hexagonal share the stagger axis/index.+ */+ES_ENUM()+enum class TilemapOrientation : u8 {+ Orthogonal = 0,+ Isometric = 1,+ Staggered = 2,+ Hexagonal = 3,+};++/** Which axis the stagger runs along (Tiled staggeraxis). Y = rows shift, X = columns shift. */+ES_ENUM()+enum class TilemapStaggerAxis : u8 {+ Y = 0,+ X = 1,+};++/** Which lines carry the half-cell shift (Tiled staggerindex). */+ES_ENUM()+enum class TilemapStaggerIndex : u8 {+ Odd = 0,+ Even = 1,+};+/*** Heavy tile data (chunks, animations, per-tile properties) lives in* TilemapSystem's LayerData keyed by this entity. Chunks flow through@@ -23,6 +50,18 @@ struct TilemapLayer {ES_PROPERTY()glm::vec2 cellSize{32.0f, 32.0f};+ ES_PROPERTY(enum=TilemapOrientation, tooltip="Grid layout: orthogonal, isometric, staggered, or hexagonal.")+ u8 orientation{0};++ ES_PROPERTY(min=0, step=1, tooltip="Hexagonal side length in px (0 = a regular pointy hex = tileHeight/2). Ignored unless orientation is Hexagonal.")+ f32 hexSideLength{0.0f};++ ES_PROPERTY(enum=TilemapStaggerAxis, tooltip="Stagger axis (staggered/hex): Y shifts rows, X shifts columns.")+ u8 staggerAxis{0};++ ES_PROPERTY(enum=TilemapStaggerIndex, tooltip="Which lines carry the half-cell shift (staggered/hex).")+ u8 staggerIndex{0};+ES_PROPERTY()glm::vec2 originOffset{0.0f, 0.0f};diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.cppindex b63536b58..5061e9b0e 100644--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp@@ -76,17 +76,17 @@ void TilemapRenderPlugin::rebuildChunk(if (layer.grid_type == tilemap::GridType::Isometric) {worldX = originX + static_cast<f32>(tx - ty) * hw;worldY = originY - static_cast<f32>(tx + ty) * hh;- } else if (layer.grid_type == tilemap::GridType::StaggeredIsometric) {- f32 offsetX = (ty & 1) ? hw : 0.0f;- worldX = originX + static_cast<f32>(tx) * layer.tile_width + offsetX + hw;- worldY = originY - static_cast<f32>(ty) * hh - hh;- } else if (layer.grid_type == tilemap::GridType::Hexagonal) {- // Tiled hexagonal layout: the stagger axis advances by- // (tile + hexSideLength)/2, staggered lines shift half a tile- // along the other axis — matches Tiled's pixel placement so- // imported maps line up 1:1.- f32 side = layer.hex_side_length > 0.0f ? layer.hex_side_length- : layer.tile_height * 0.5f;+ } else if (layer.grid_type == tilemap::GridType::StaggeredIsometric+ || layer.grid_type == tilemap::GridType::Hexagonal) {+ // Staggered/hex share one layout: the stagger axis advances by+ // (tile + side)/2, staggered lines shift half a tile along the+ // other axis — matching Tiled's pixel placement so imported maps+ // line up 1:1. Staggered iso is exactly hex with side length 0;+ // hex with side 0 falls back to a regular pointy hex.+ bool isHex = layer.grid_type == tilemap::GridType::Hexagonal;+ f32 side = isHex ? (layer.hex_side_length > 0.0f ? layer.hex_side_length+ : layer.tile_height * 0.5f)+ : 0.0f;if (layer.hex_stagger_axis_x) {f32 colW = (layer.tile_width + side) * 0.5f;bool staggered = ((tx & 1) != 0) != layer.hex_stagger_index_even;diff --git a/src/esengine/tilemap/TilemapSystem.cpp b/src/esengine/tilemap/TilemapSystem.cppindex 9a8aafcb4..21b2ce53b 100644--- a/src/esengine/tilemap/TilemapSystem.cpp+++ b/src/esengine/tilemap/TilemapSystem.cpp@@ -374,17 +374,16 @@ void TilemapSystem::tileToWorld(Entity entity, i32 tx, i32 ty,outX = originX + static_cast<f32>(tx - ty) * tw * 0.5f;outY = originY - static_cast<f32>(tx + ty) * th * 0.5f;break;- case GridType::StaggeredIsometric: {- f32 offsetX = (ty & 1) ? tw * 0.5f : 0.0f;- outX = originX + static_cast<f32>(tx) * tw + offsetX;- outY = originY - static_cast<f32>(ty) * th * 0.5f;- break;- }+ case GridType::StaggeredIsometric:case GridType::Hexagonal: {- // Tiled hexagonal layout: the stagger axis advances by- // (tile + hexSideLength)/2 and staggered lines shift half a tile- // along the other axis (staggerindex picks odd or even lines).- f32 side = layer->hex_side_length > 0.0f ? layer->hex_side_length : th * 0.5f;+ // Staggered/hex share one layout: the stagger axis advances by+ // (tile + side)/2 and staggered lines shift half a tile along the+ // other axis (staggerindex picks odd or even lines). Staggered iso+ // is exactly hex with side length 0; hex with side 0 falls back to a+ // regular pointy hex (side = tileHeight/2).+ bool isHex = layer->grid_type == GridType::Hexagonal;+ f32 side = isHex ? (layer->hex_side_length > 0.0f ? layer->hex_side_length : th * 0.5f)+ : 0.0f;if (layer->hex_stagger_axis_x) {f32 colW = (tw + side) * 0.5f;bool staggered = ((tx & 1) != 0) != layer->hex_stagger_index_even;@@ -424,17 +423,14 @@ void TilemapSystem::worldToTile(Entity entity, f32 wx, f32 wy,outTy = static_cast<i32>(std::floor(fty));break;}- case GridType::StaggeredIsometric: {- i32 roughY = static_cast<i32>(std::floor(ly / (th * 0.5f)));- f32 offsetX = (roughY & 1) ? tw * 0.5f : 0.0f;- outTx = static_cast<i32>(std::floor((lx - offsetX) / tw));- outTy = roughY;- break;- }+ case GridType::StaggeredIsometric:case GridType::Hexagonal: {- // Box-approximate like the staggered-iso case: resolve the stagger- // line first, then the cell along it (no exact hex hit-test).- f32 side = layer->hex_side_length > 0.0f ? layer->hex_side_length : th * 0.5f;+ // Box-approximate: resolve the stagger line first, then the cell+ // along it (no exact hex hit-test). Staggered iso is hex with side+ // length 0; hex with side 0 falls back to a regular pointy hex.+ bool isHex = layer->grid_type == GridType::Hexagonal;+ f32 side = isHex ? (layer->hex_side_length > 0.0f ? layer->hex_side_length : th * 0.5f)+ : 0.0f;if (layer->hex_stagger_axis_x) {f32 colW = (tw + side) * 0.5f;i32 roughX = static_cast<i32>(std::floor(lx / colW));