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): named render sorting layers for the layer field

esengine2c562ffdf235
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.ts
index 53b1aee72..1ca34ccf5 100644
--- a/desktop/electron/extractSchemas.ts
+++ b/desktop/electron/extractSchemas.ts
@@ -62,6 +62,7 @@ export interface ComponentSchema {
/** The serialized editor metadata of one component field. */
export interface SerializedFieldMeta {
enum?: Array<{ label: string; value: number }>;
+ enumSource?: string;
flags?: Array<{ label: string; value: number }>;
bitmask?: { bits?: number; source?: string };
min?: number;
@@ -208,6 +209,7 @@ function pickFieldMeta(
for (const [key, meta] of Object.entries(fieldMeta)) {
const m: SerializedFieldMeta = {};
if (meta.enum && meta.enum.length) m.enum = meta.enum.map((o) => ({ ...o }));
+ if (meta.enumSource) m.enumSource = meta.enumSource;
if (meta.flags && meta.flags.length) m.flags = meta.flags.map((o) => ({ ...o }));
if (meta.bitmask) m.bitmask = { ...meta.bitmask };
if (meta.min != null) m.min = meta.min;
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index f382c7419..7adc2d37c 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -188,6 +188,7 @@ export interface UserComponentSchema {
/** A serialized field's editor metadata, as carried in `schemas.json`. */
export interface UserFieldMeta {
enum?: EnumOption[];
+ enumSource?: string;
flags?: EnumOption[];
bitmask?: { bits?: number; source?: string };
min?: number;
@@ -264,6 +265,7 @@ export function fieldMetaFor(compType: string, key: string): UserFieldMeta | nul
if (fromDef) {
return {
enum: fromDef.enum?.map((o) => ({ label: o.label, value: o.value })),
+ enumSource: fromDef.enumSource,
flags: fromDef.flags?.map((o) => ({ label: o.label, value: o.value })),
bitmask: fromDef.bitmask,
min: fromDef.min,
@@ -293,6 +295,19 @@ export function setBitmaskSource(name: string, provider: (() => EnumOption[]) |
if (provider) bitmaskSources.set(name, provider);
else bitmaskSources.delete(name);
}
+
+// Editor-registered providers of dynamic enum options (e.g. project sorting
+// layers). A field with `enumSource` becomes a dropdown when its source yields
+// options, else a plain number — so free-int editing survives an empty set.
+const enumSources = new Map<string, () => EnumOption[]>();
+/** Register (or clear) a named source of dynamic enum options. */
+export function setEnumSource(name: string, provider: (() => EnumOption[]) | null): void {
+ if (provider) enumSources.set(name, provider);
+ else enumSources.delete(name);
+}
+function enumSourceOptions(name: string): EnumOption[] {
+ return enumSources.get(name)?.() ?? [];
+}
/** The bit options for a bitmask field: its source's labels, else `Layer N`. */
function bitmaskOptions(meta: { bits?: number; source?: string }): EnumOption[] {
const src = meta.source ? bitmaskSources.get(meta.source) : undefined;
@@ -322,6 +337,8 @@ function fieldFor(
field = { key, label: prettyLabel(key), type: 'flags', value: Number(value) || 0, options: meta.flags.map((o) => ({ ...o })) };
} else if (meta?.enum && meta.enum.length) {
field = { key, label: prettyLabel(key), type: 'enum', value: Number(value) || 0, options: meta.enum.map((o) => ({ ...o })) };
+ } else if (meta?.enumSource && enumSourceOptions(meta.enumSource).length) {
+ field = { key, label: prettyLabel(key), type: 'enum', value: Number(value) || 0, options: enumSourceOptions(meta.enumSource) };
} else {
field = inferField(key, value, isColor);
if (field && field.type === 'number' && meta) {
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 31bdeeab5..901cd328f 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -10,7 +10,7 @@ import { EditorHistory } from '@/engine/EditorHistory';
import { expandScenePrefabs, collapseScenePrefabs } from '@/engine/PrefabInstance';
import { SceneCommands } from '@/engine/SceneCommands';
import { setPrefabBaseResolver } from '@/engine/SceneQuery';
-import { setUserSchemas, userSchema, setBitmaskSource, type UserComponentSchema } from '@/engine/schema';
+import { setUserSchemas, userSchema, setBitmaskSource, setEnumSource, type UserComponentSchema } from '@/engine/schema';
import { useSelection } from '@/store/selectionStore';
import { Toasts } from '@/store/Toasts';
import { assetTypeOf } from '@/project/assetMeta';
@@ -115,6 +115,8 @@ class ProjectStoreImpl {
});
// Collider layer-mask fields resolve their bit labels from this project setting.
setBitmaskSource('collisionLayers', () => this.collisionLayerOptions());
+ // Render `layer` fields become a dropdown once the project names sorting layers.
+ setEnumSource('sortingLayers', () => this.sortingLayerOptions());
}
/** Read accessor so existing `this.state` reads stay unchanged after the move. */
@@ -526,6 +528,37 @@ class ProjectStoreImpl {
return names.map((name, i) => ({ label: name || `Layer ${i}`, value: 1 << i }));
}
+ /** Named render sorting layers (z-order = slot index). Default empty list. */
+ renderingFeature(): { sortingLayers: string[] } {
+ const r = this.state?.features?.rendering;
+ return { sortingLayers: Array.from({ length: 8 }, (_, i) => r?.sortingLayers?.[i] ?? '') };
+ }
+
+ /** Sorting-layer dropdown options for render `layer` fields — only the NAMED
+ * slots (value = slot index = z-order); empty ⇒ the field stays a free number. */
+ sortingLayerOptions(): Array<{ label: string; value: number }> {
+ return this.renderingFeature()
+ .sortingLayers.map((name, i) => ({ label: name.trim(), value: i }))
+ .filter((o) => o.label !== '');
+ }
+
+ /** Set rendering-feature config (sorting layers) and persist to the manifest. */
+ async setRendering(patch: { sortingLayers?: string[] }): Promise<void> {
+ const st = this.state;
+ if (!st) return;
+ const rendering: NonNullable<ProjectFeatures['rendering']> = { ...st.features?.rendering, ...patch };
+ const features: ProjectFeatures = { ...st.features, rendering };
+ this.store.setState({ project: { ...st, features } });
+ try {
+ const raw = JSON.parse(await window.estella.fs.read(PROJECT_MANIFEST_FILE)) as Record<string, unknown>;
+ raw.features = { ...((raw.features as Record<string, unknown>) ?? {}), rendering };
+ await window.estella.fs.write(PROJECT_MANIFEST_FILE, JSON.stringify(raw, null, 2) + '\n');
+ } catch (e) {
+ Toasts.push('Failed to save sorting layers', 'error');
+ console.error('[project] setRendering write failed', e);
+ }
+ }
+
/**
* Enable/configure the project's physics feature and persist to
* `project.esproject` (so the play realm installs physics even for
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index 246a214e1..3368c0cb4 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -70,6 +70,10 @@ export interface ProjectFeatures {
/** Names for the 16 Box2D collision-filter layers (the inspector's layer masks). */
collisionLayers?: string[];
};
+ rendering?: {
+ /** Named render sorting layers (the inspector's `layer` dropdown); index = z-order. */
+ sortingLayers?: string[];
+ };
}
/** Committed project identity + config (`project.esproject`). */
@@ -195,6 +199,12 @@ export function parseManifest(raw: unknown): ProjectManifest {
}
features.physics = physics;
}
+ if (f.rendering && typeof f.rendering === 'object') {
+ const r = f.rendering as Record<string, unknown>;
+ if (Array.isArray(r.sortingLayers)) {
+ features.rendering = { sortingLayers: r.sortingLayers.slice(0, 32).map((n) => (typeof n === 'string' ? n : '')) };
+ }
+ }
if (Object.keys(features).length > 0) manifest.features = features;
}
return manifest;
diff --git a/desktop/src/settings/projectSettings.ts b/desktop/src/settings/projectSettings.ts
index 02753bec6..a4b91c5bd 100644
--- a/desktop/src/settings/projectSettings.ts
+++ b/desktop/src/settings/projectSettings.ts
@@ -13,6 +13,26 @@ import { ProjectStore } from '@/project/ProjectStore';
// ── Physics (the enable flag = UE Plugins-Browser analog; gravity = Project Settings) ──
settingsRegistry.registerSection({ id: 'physics', label: 'Physics', category: 'project', order: 1 });
+// ── Rendering (named sorting layers feed the inspector's render `layer` dropdown) ──
+settingsRegistry.registerSection({ id: 'rendering', label: 'Rendering', category: 'project', order: 2 });
+
+settingsRegistry.register({
+ id: 'project.rendering.sortingLayers',
+ type: 'stringList',
+ scope: 'project',
+ section: 'rendering',
+ group: 'Sorting Layers',
+ label: 'Layer names',
+ description: 'Name render sorting layers (lowest first); a render `layer` field then picks from them instead of a raw number.',
+ count: 8,
+ placeholder: (i) => `Layer ${i}`,
+ default: Array.from({ length: 8 }, () => ''),
+ bind: {
+ get: () => ProjectStore.renderingFeature().sortingLayers,
+ set: (v) => void ProjectStore.setRendering({ sortingLayers: v }),
+ },
+});
+
settingsRegistry.register({
id: 'project.physics.enabled',
type: 'boolean',
diff --git a/desktop/tests/inspector-model.test.ts b/desktop/tests/inspector-model.test.ts
index 675d88f74..21eb10e82 100644
--- a/desktop/tests/inspector-model.test.ts
+++ b/desktop/tests/inspector-model.test.ts
@@ -14,7 +14,7 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import type { SceneData } from 'esengine';
import { EditorSession } from '@/engine/EditorSession';
-import { setUserSchemas, enumFieldOptions, setBitmaskSource } from '@/engine/schema';
+import { setUserSchemas, enumFieldOptions, setBitmaskSource, setEnumSource } from '@/engine/schema';
import { setPrefabBaseResolver } from '@/engine/SceneQuery';
/** A one-entity scene carrying a Camera with the given component-data overrides. */
@@ -292,6 +292,38 @@ describe('Unknown-component inspector (schemas.json consumer)', () => {
});
});
+describe('Sorting-layer enum source (render layer)', () => {
+ afterEach(() => setEnumSource('sortingLayers', null));
+ function spriteScene(layer: number): SceneData {
+ return {
+ version: '1.0',
+ name: 's',
+ entities: [{ id: 1, name: 'S', parent: null, children: [], components: [{ type: 'Sprite', data: { layer } }] }],
+ } as unknown as SceneData;
+ }
+ const layerField = (S: EditorSession) =>
+ S.query.readInspector(1).find((c) => c.name === 'Sprite')!.fields.find((f) => f.key === 'layer')!;
+
+ it('a render layer stays a free number when no sorting layers are named', () => {
+ const S = EditorSession.create();
+ S.model.adopt(spriteScene(3), new Map([[1, 1]]));
+ const lf = layerField(S);
+ expect(lf.type).toBe('number');
+ expect(lf.value).toBe(3);
+ expect(lf.step).toBe(1);
+ });
+
+ it('becomes a named dropdown once sorting layers are defined', () => {
+ setEnumSource('sortingLayers', () => [{ label: 'Background', value: 0 }, { label: 'Foreground', value: 1 }]);
+ const S = EditorSession.create();
+ S.model.adopt(spriteScene(1), new Map([[1, 1]]));
+ const lf = layerField(S);
+ expect(lf.type).toBe('enum');
+ expect(lf.value).toBe(1);
+ expect(lf.options!.map((o) => o.label)).toEqual(['Background', 'Foreground']);
+ });
+});
+
describe('Bitmask fields (collision layers)', () => {
afterEach(() => setBitmaskSource('collisionLayers', null));
function colliderScene(categoryBits: number): SceneData {
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index f5f5a7d3e..d6f60abb4 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -34,6 +34,12 @@ export interface AssetRef {
export interface FieldMeta {
/** Render as a dropdown of these options; the stored value is the option's int. */
enum?: ReadonlyArray<{ label: string; value: number }>;
+ /**
+ * Render as a dropdown whose options are resolved by the editor from a named
+ * source (e.g. project sorting layers) — falls back to a plain number when the
+ * source yields none, so free-int editing survives a project with no named set.
+ */
+ enumSource?: string;
/** Render as a bitmask multi-select; each option is a single bit. */
flags?: ReadonlyArray<{ label: string; value: number }>;
/**
@@ -564,7 +570,7 @@ export const Sprite = defineBuiltin<SpriteData>('Sprite',
}),
{
fields: {
- layer: { step: 1 },
+ layer: { step: 1, enumSource: 'sortingLayers' },
pivot: { advanced: true },
uvOffset: { advanced: true },
uvScale: { advanced: true },
@@ -581,7 +587,7 @@ export const ShapeRenderer = defineBuiltin<ShapeRendererData>('ShapeRenderer',
fields: {
shapeType: { enum: enumOptions(ShapeType) },
cornerRadius: { min: 0 },
- layer: { step: 1 },
+ layer: { step: 1, enumSource: 'sortingLayers' },
},
}
);
@@ -651,7 +657,7 @@ export const SpineAnimation = defineBuiltin<SpineAnimationData>('SpineAnimation'
fields: {
timeScale: { min: 0 },
skeletonScale: { min: 0 },
- layer: { step: 1 },
+ layer: { step: 1, enumSource: 'sortingLayers' },
},
}
);
@@ -663,7 +669,7 @@ export const TilemapLayer = defineBuiltin<TilemapLayerData>('TilemapLayer',
opacity: { min: 0, max: 1, slider: true },
tilesetColumns: { min: 1, step: 1 },
tilesetRows: { min: 1, step: 1 },
- renderLayer: { step: 1 },
+ renderLayer: { step: 1, enumSource: 'sortingLayers' },
},
}
);
@@ -787,7 +793,7 @@ export const ParticleEmitter = defineBuiltin<ParticleEmitterData>('ParticleEmitt
spriteFPS: { min: 0, category: 'Texture' },
spriteLoop: { category: 'Texture' },
blendMode: { enum: enumOptions(BlendMode), category: 'Rendering' },
- layer: { step: 1, category: 'Rendering' },
+ layer: { step: 1, category: 'Rendering', enumSource: 'sortingLayers' },
material: { category: 'Rendering' },
simulationSpace: { enum: enumOptions(SimulationSpace), category: 'Rendering' },
},