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(editor): named render sorting layers for the layer field
esengine2c562ffdf235
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.tsindex 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.tsindex 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 | nulif (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.tsindex 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 fordiff --git a/desktop/src/project/format.ts b/desktop/src/project/format.tsindex 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.tsindex 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.tsindex 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.tsindex 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>('ParticleEmittspriteFPS: { 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' },},