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): expand the Create catalog beyond UI (Empty, 2D, Camera, Light…)

yhhd289598bd8cd
diff --git a/desktop/src/engine/entityTemplates.ts b/desktop/src/engine/entityTemplates.ts
index 31d5e2dd0..2fa7f7e5a 100644
--- a/desktop/src/engine/entityTemplates.ts
+++ b/desktop/src/engine/entityTemplates.ts
@@ -4,12 +4,15 @@
* @file entityTemplates.ts — the Create-menu catalog.
*
* One declarative registry of ready-made entities, grouped by category, that the
- * Outliner's "Create ▸" menu is generated from — instead of hand-adding a blank
- * entity and stacking components. UI controls come from the SDK's built-in widget
- * prefabs (generated from the factories). New categories (2D, lights, …) slot in
- * here without touching the menu code.
+ * Outliner's "Create" popover is generated from — instead of hand-adding a blank
+ * entity and stacking components. Every template is a single PrefabData, so they
+ * all instantiate through the same SceneCommands.createFromTemplate path: UI
+ * controls are the SDK's generated widget prefabs; the rest are one-entity presets
+ * built from the registered component defaults. New categories/items slot in here
+ * without touching the menu code.
*/
-import { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES, type PrefabData } from 'esengine';
+import { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES, PREFAB_FORMAT_VERSION, type PrefabData } from 'esengine';
+import { componentByName, componentDefaults } from './schema';
export interface EntityTemplate {
label: string;
@@ -24,14 +27,51 @@ export interface TemplateCategory {
items: EntityTemplate[];
}
+type CompSpec = string | [string, Record<string, unknown>];
+
+/** A one-entity template prefab from the registered component defaults + overrides. */
+function preset(name: string, comps: CompSpec[]): PrefabData {
+ const components = comps.map((c) => {
+ const [type, over] = Array.isArray(c) ? c : [c, undefined];
+ const def = componentByName(type);
+ const base = def ? structuredClone(componentDefaults(def)) : {};
+ return { type, data: over ? { ...base, ...over } : base };
+ });
+ return {
+ version: PREFAB_FORMAT_VERSION,
+ name,
+ rootEntityId: '0',
+ entities: [{ prefabEntityId: '0', name, parent: null, children: [], components, visible: true }],
+ };
+}
+
export const ENTITY_TEMPLATE_CATALOG: TemplateCategory[] = [
+ {
+ label: 'Basic',
+ items: [{ label: 'Empty', prefab: preset('Empty', ['Transform']) }],
+ },
+ {
+ label: '2D',
+ items: [
+ { label: 'Sprite', prefab: preset('Sprite', ['Transform', 'Sprite']) },
+ { label: 'Camera', prefab: preset('Camera', [['Transform', { position: { x: 0, y: 0, z: 10 } }], 'Camera']) },
+ { label: 'Particles', prefab: preset('Particles', ['Transform', 'ParticleEmitter']) },
+ { label: 'Light', prefab: preset('Light', ['Transform', 'Light2D']) },
+ ],
+ },
{
label: 'UI',
- items: BUILTIN_UI_WIDGET_NAMES.map((name) => ({
- label: name,
- prefab: BUILTIN_UI_PREFABS[name]!,
- underCanvas: true,
- })),
+ items: [
+ {
+ label: 'Canvas',
+ prefab: preset('Canvas', ['Transform', ['Canvas', { designResolution: { x: 800, y: 600 }, scaleMode: 2 }], 'UINode']),
+ },
+ ...BUILTIN_UI_WIDGET_NAMES.map((name) => ({
+ label: name,
+ prefab: BUILTIN_UI_PREFABS[name]!,
+ underCanvas: true,
+ })),
+ ],
},
];
diff --git a/desktop/tests/create-catalog.test.ts b/desktop/tests/create-catalog.test.ts
index 830fc3366..fb92f2a3d 100644
--- a/desktop/tests/create-catalog.test.ts
+++ b/desktop/tests/create-catalog.test.ts
@@ -4,22 +4,33 @@ import { describe, it, expect } from 'vitest';
import { flattenCatalog, matchCatalog } from '@/engine/entityTemplates';
describe('Create catalog (searchable template list)', () => {
- it('flattens categories into a list, preserving order + carrying category', () => {
+ it('spans Basic / 2D / UI, preserving order + carrying category', () => {
const all = flattenCatalog();
- expect(all.length).toBeGreaterThan(0);
- expect(all.every((e) => e.category !== '' && e.template.label !== '')).toBe(true);
- expect(all.map((e) => e.template.label)).toEqual(expect.arrayContaining(['Button', 'Slider']));
+ expect(all.map((e) => e.template.label)).toEqual(
+ expect.arrayContaining(['Empty', 'Sprite', 'Camera', 'Canvas', 'Button', 'Slider']),
+ );
+ expect(new Set(all.map((e) => e.category))).toEqual(new Set(['Basic', '2D', 'UI']));
+ });
+
+ it('builds one-entity presets from the registered component defaults', () => {
+ const all = flattenCatalog();
+ const camera = all.find((e) => e.template.label === 'Camera')!.template.prefab.entities[0];
+ expect(camera.components.map((c) => c.type)).toEqual(['Transform', 'Camera']);
+ const cam = camera.components.find((c) => c.type === 'Camera')!.data as Record<string, unknown>;
+ expect(cam.isActive).toBe(true); // orthographic + active come from Camera's defaults
+
+ const empty = all.find((e) => e.template.label === 'Empty')!.template.prefab.entities[0];
+ expect(empty.components.map((c) => c.type)).toEqual(['Transform']);
});
it('matches on item label, case-insensitively', () => {
const all = flattenCatalog();
- const r = matchCatalog(all, 'BUT');
- expect(r.map((e) => e.template.label)).toEqual(['Button']);
+ expect(matchCatalog(all, 'CAM').map((e) => e.template.label)).toEqual(['Camera']);
});
it('matches on category label', () => {
const all = flattenCatalog();
- expect(matchCatalog(all, 'ui').length).toBe(all.length); // every current template is UI
+ expect(matchCatalog(all, '2d').map((e) => e.template.label)).toEqual(['Sprite', 'Camera', 'Particles', 'Light']);
});
it('empty query returns everything; no match returns nothing', () => {
diff --git a/desktop/tests/engine-commands.test.ts b/desktop/tests/engine-commands.test.ts
index 648516792..89bce481f 100644
--- a/desktop/tests/engine-commands.test.ts
+++ b/desktop/tests/engine-commands.test.ts
@@ -32,6 +32,7 @@ vi.mock('@/engine/EngineHost', () => ({
}));
import { EditorSession } from '@/engine/EditorSession';
+import { flattenCatalog } from '@/engine/entityTemplates';
import type { SceneData } from 'esengine';
const emptyScene = (): SceneData =>
@@ -207,4 +208,11 @@ describe.skipIf(!HAS_WASM)('SceneCommands / SceneQuery (headless World)', () =>
expect(host.world.valid(e)).toBe(false);
expect(host.world.valid(ce)).toBe(false);
});
+
+ it('a non-UI catalog preset (Sprite) instantiates into the World', () => {
+ const sprite = flattenCatalog().find((c) => c.template.label === 'Sprite')!;
+ const id = S.commands.createFromTemplate(sprite.template.prefab, null)!;
+ expect(id).not.toBeNull();
+ expect(host.world.has(rt(id), Sprite)).toBe(true);
+ });
});