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.

fix(desktop): packaged editor ships new-project templates (blank starter + example gallery)

yhh80c4c6be22c2
diff --git a/.gitignore b/.gitignore
index c6bbbd346..10e2b2755 100644
--- a/.gitignore
+++ b/.gitignore
@@ -80,7 +80,6 @@ desktop/.cooked-src/
.astro/
# Examples
-desktop/public/examples/
examples/tools/
# OS files
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 9ca3a51ee..693f18c30 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -16,7 +16,6 @@ import { syncToDesktop } from './tasks/sync.js';
import { startWatch } from './tasks/watch.js';
import { BuildManifest } from './manifest.js';
import { handleBuildError } from './utils/errorHelp.js';
-import { zipExamples } from './tasks/examples.js';
import { checkExamples } from './tasks/check-examples.js';
program
@@ -204,16 +203,6 @@ async function cleanAll() {
await cleanSdk();
}
-program
- .command('zip-examples')
- .description('Pack example projects into zip files for editor')
- .action(async () => {
- logger.header('Zip Examples');
- const startTime = Date.now();
- await zipExamples(config.paths.root);
- logger.printTime(Date.now() - startTime);
- });
-
program
.command('check-examples')
.description('Type-check all example projects against current SDK types')
diff --git a/build-tools/tasks/check-examples.js b/build-tools/tasks/check-examples.js
index 266893610..f83d714e6 100644
--- a/build-tools/tasks/check-examples.js
+++ b/build-tools/tasks/check-examples.js
@@ -11,20 +11,25 @@ import { execSync } from 'child_process';
import { fileURLToPath } from 'url';
import * as logger from '../utils/logger.js';
-const EXAMPLES_DIR = 'examples';
+// Every project directory that ships to users: the examples plus the editor's
+// bundled new-project templates (desktop/templates).
+const PROJECT_ROOTS = ['examples', 'desktop/templates'];
function discoverExamples(rootDir) {
- const examplesPath = path.join(rootDir, EXAMPLES_DIR);
- if (!existsSync(examplesPath)) return [];
-
- return readdirSync(examplesPath)
- .filter(entry => {
- const fullPath = path.join(examplesPath, entry);
- return statSync(fullPath).isDirectory() &&
+ const out = [];
+ for (const rel of PROJECT_ROOTS) {
+ const rootPath = path.join(rootDir, rel);
+ if (!existsSync(rootPath)) continue;
+ for (const entry of readdirSync(rootPath)) {
+ const fullPath = path.join(rootPath, entry);
+ if (statSync(fullPath).isDirectory() &&
existsSync(path.join(fullPath, 'tsconfig.json')) &&
- existsSync(path.join(fullPath, 'src'));
- })
- .map(name => ({ name, dir: path.join(rootDir, EXAMPLES_DIR, name) }));
+ existsSync(path.join(fullPath, 'src'))) {
+ out.push({ name: entry, dir: fullPath });
+ }
+ }
+ }
+ return out;
}
function setupTypeLinks(exampleDir, rootDir) {
diff --git a/build-tools/tasks/examples.js b/build-tools/tasks/examples.js
deleted file mode 100644
index a6e6452ea..000000000
--- a/build-tools/tasks/examples.js
+++ /dev/null
@@ -1,173 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file examples.js
- * @brief Pack example projects into zip files for editor
- */
-
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, copyFileSync } from 'fs';
-import path from 'path';
-import { deflateRawSync } from 'zlib';
-import * as logger from '../utils/logger.js';
-
-const EXAMPLES_DIR = 'examples';
-const OUTPUT_DIR = 'desktop/public/examples';
-const THUMBNAILS_DIR = 'thumbnails';
-const THUMBNAIL_FILENAME = 'thumbnail.png';
-
-function discoverExamples(rootDir) {
- const examplesPath = path.join(rootDir, EXAMPLES_DIR);
- if (!existsSync(examplesPath)) return [];
-
- return readdirSync(examplesPath)
- .filter(entry => {
- const fullPath = path.join(examplesPath, entry);
- return statSync(fullPath).isDirectory() &&
- existsSync(path.join(fullPath, 'project.esproject'));
- })
- .map(name => ({ name, dir: path.join(EXAMPLES_DIR, name) }));
-}
-
-const EXCLUDE_PATTERNS = [
- '.DS_Store',
- 'node_modules',
- 'dist',
- '.esengine/cache',
- 'tools',
- '__pycache__',
-];
-
-function shouldExclude(relativePath) {
- for (const pattern of EXCLUDE_PATTERNS) {
- if (relativePath === pattern || relativePath.startsWith(pattern + '/') ||
- relativePath.includes('/' + pattern + '/') || relativePath.endsWith('/' + pattern)) {
- return true;
- }
- }
- return false;
-}
-
-function collectFiles(dir, baseDir) {
- const results = [];
- for (const entry of readdirSync(dir)) {
- const fullPath = path.join(dir, entry);
- const relativePath = path.relative(baseDir, fullPath).split(path.sep).join('/');
- if (shouldExclude(relativePath)) continue;
- const stat = statSync(fullPath);
- if (stat.isDirectory()) {
- results.push(...collectFiles(fullPath, baseDir));
- } else {
- results.push({ fullPath, relativePath });
- }
- }
- return results;
-}
-
-function crc32(buf) {
- let crc = 0xffffffff;
- for (let i = 0; i < buf.length; i++) {
- crc ^= buf[i];
- for (let j = 0; j < 8; j++) {
- crc = (crc >>> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
- }
- }
- return (crc ^ 0xffffffff) >>> 0;
-}
-
-function createZip(srcDir, outputPath) {
- const files = collectFiles(srcDir, srcDir);
- const localParts = [];
- const centralEntries = [];
- let offset = 0;
-
- for (const file of files) {
- const content = readFileSync(file.fullPath);
- const compressed = deflateRawSync(content);
- const nameBytes = Buffer.from(file.relativePath, 'utf8');
- const crc = crc32(content);
-
- const local = Buffer.alloc(30);
- local.writeUInt32LE(0x04034b50, 0);
- local.writeUInt16LE(20, 4);
- local.writeUInt16LE(0, 6);
- local.writeUInt16LE(8, 8);
- local.writeUInt16LE(0, 10);
- local.writeUInt16LE(0, 12);
- local.writeUInt32LE(crc, 14);
- local.writeUInt32LE(compressed.length, 18);
- local.writeUInt32LE(content.length, 22);
- local.writeUInt16LE(nameBytes.length, 26);
- local.writeUInt16LE(0, 28);
-
- localParts.push(local, nameBytes, compressed);
-
- const central = Buffer.alloc(46);
- central.writeUInt32LE(0x02014b50, 0);
- central.writeUInt16LE(20, 4);
- central.writeUInt16LE(20, 6);
- central.writeUInt16LE(0, 8);
- central.writeUInt16LE(8, 10);
- central.writeUInt16LE(0, 12);
- central.writeUInt16LE(0, 14);
- central.writeUInt32LE(crc, 16);
- central.writeUInt32LE(compressed.length, 20);
- central.writeUInt32LE(content.length, 24);
- central.writeUInt16LE(nameBytes.length, 28);
- central.writeUInt32LE(offset, 42);
-
- centralEntries.push(central, nameBytes);
- offset += 30 + nameBytes.length + compressed.length;
- }
-
- const centralDirOffset = offset;
- let centralDirSize = 0;
- for (const buf of centralEntries) centralDirSize += buf.length;
-
- const eocd = Buffer.alloc(22);
- eocd.writeUInt32LE(0x06054b50, 0);
- eocd.writeUInt16LE(files.length, 8);
- eocd.writeUInt16LE(files.length, 10);
- eocd.writeUInt32LE(centralDirSize, 12);
- eocd.writeUInt32LE(centralDirOffset, 16);
-
- writeFileSync(outputPath, Buffer.concat([...localParts, ...centralEntries, eocd]));
-}
-
-export async function zipExamples(rootDir) {
- logger.step('Packing example projects...');
-
- const examples = discoverExamples(rootDir);
- if (examples.length === 0) {
- logger.warn('No example projects found');
- return;
- }
-
- const outDir = path.join(rootDir, OUTPUT_DIR);
- if (!existsSync(outDir)) {
- mkdirSync(outDir, { recursive: true });
- }
-
- const thumbDir = path.join(outDir, THUMBNAILS_DIR);
- if (!existsSync(thumbDir)) {
- mkdirSync(thumbDir, { recursive: true });
- }
-
- for (const example of examples) {
- const srcDir = path.join(rootDir, example.dir);
- const zipPath = path.join(outDir, `${example.name}.zip`);
-
- try {
- createZip(srcDir, zipPath);
- logger.success(`${example.name}.zip`);
- } catch (err) {
- logger.error(`Failed to zip ${example.name}: ${err.message}`);
- }
-
- const thumbSrc = path.join(srcDir, THUMBNAIL_FILENAME);
- if (existsSync(thumbSrc)) {
- const thumbDest = path.join(thumbDir, `${example.name}.png`);
- copyFileSync(thumbSrc, thumbDest);
- logger.success(`${example.name} thumbnail`);
- }
- }
-}
diff --git a/desktop/electron-builder.yml b/desktop/electron-builder.yml
index 81e647aa7..33effac94 100644
--- a/desktop/electron-builder.yml
+++ b/desktop/electron-builder.yml
@@ -11,6 +11,9 @@ directories:
output: release
files:
- dist/**
+ # Stale example zips from the retired zip-examples task (gitignored, may
+ # linger in contributors' public/ and ride into dist/) must not ship.
+ - "!dist/examples/**"
- dist-electron/**
- package.json
# Trees the runtime consumes as REAL files, not through Electron's patched fs:
@@ -34,6 +37,24 @@ asarUnpack:
extraResources:
- from: ../build-tools/basis
to: build-tools/basis
+ # New-project templates: the bundled blank-slate starter(s) plus the sample
+ # projects, staged as real directories (createFromTemplate copies a template
+ # with fs.cp, which cannot source from inside the asar). The launcher reads
+ # resources/templates then resources/examples — see electron/launcher.ts.
+ - from: templates
+ to: templates
+ filter:
+ - "**/*"
+ - "!**/.esengine/**"
+ - "!**/node_modules/**"
+ - "!**/dist/**"
+ - from: ../examples
+ to: examples
+ filter:
+ - "**/*"
+ - "!**/.esengine/**"
+ - "!**/node_modules/**"
+ - "!**/dist/**"
win:
target: nsis
mac:
diff --git a/desktop/electron/launcher.ts b/desktop/electron/launcher.ts
index 1eda70ada..5d9cb060d 100644
--- a/desktop/electron/launcher.ts
+++ b/desktop/electron/launcher.ts
@@ -12,6 +12,7 @@ import { existsSync } from 'node:fs';
import path from 'node:path';
import {
PROJECT_MANIFEST_FILE,
+ isTransientProjectPath,
parseManifest,
type RecentEntry,
type TemplateEntry,
@@ -101,37 +102,58 @@ export async function removeRecent(root: string): Promise<void> {
await writeFile(recentsFile(), JSON.stringify(stored, null, 2));
}
-// New-project templates. In dev these are the in-repo examples (each is a real
-// project dir); a packaged build would point this at a bundled templates dir.
-const templatesDir = (): string => path.join(process.env.APP_ROOT ?? '', '..', 'examples');
+// New-project template roots, in gallery order: bundled blank-slate starters
+// first, then the sample projects (each root holds real project dirs). Dev
+// reads the in-repo trees; a packaged app reads the copies electron-builder
+// stages under resources/ (extraResources — real files, outside the asar, so
+// createFromTemplate's directory copy works on them).
+const templateRoots = (): Array<{ root: string; kind: TemplateEntry['kind'] }> =>
+ app.isPackaged
+ ? [
+ { root: path.join(process.resourcesPath, 'templates'), kind: 'starter' },
+ { root: path.join(process.resourcesPath, 'examples'), kind: 'example' },
+ ]
+ : [
+ { root: path.join(process.env.APP_ROOT ?? '', 'templates'), kind: 'starter' },
+ { root: path.join(process.env.APP_ROOT ?? '', '..', 'examples'), kind: 'example' },
+ ];
export async function listTemplates(): Promise<TemplateEntry[]> {
- const root = templatesDir();
- if (!existsSync(root)) return [];
const out: TemplateEntry[] = [];
- for (const entry of await readdir(root, { withFileTypes: true })) {
- if (!entry.isDirectory()) continue;
- const dir = path.join(root, entry.name);
- if (!existsSync(path.join(dir, PROJECT_MANIFEST_FILE))) continue;
- let description: string | undefined;
- let tag: string | undefined;
- try {
- const m = parseManifest(JSON.parse(await readFile(path.join(dir, PROJECT_MANIFEST_FILE), 'utf8')));
- description = m.description;
- tag = m.tag;
- } catch {
- // keep name-only
+ const seen = new Set<string>();
+ for (const { root, kind } of templateRoots()) {
+ if (!existsSync(root)) continue;
+ for (const entry of await readdir(root, { withFileTypes: true })) {
+ if (!entry.isDirectory() || seen.has(entry.name)) continue;
+ const dir = path.join(root, entry.name);
+ if (!existsSync(path.join(dir, PROJECT_MANIFEST_FILE))) continue;
+ seen.add(entry.name);
+ let name = entry.name;
+ let description: string | undefined;
+ let tag: string | undefined;
+ try {
+ const m = parseManifest(JSON.parse(await readFile(path.join(dir, PROJECT_MANIFEST_FILE), 'utf8')));
+ name = m.name;
+ description = m.description;
+ tag = m.tag;
+ } catch {
+ // keep dir-name-only
+ }
+ out.push({ name, dir, kind, description, tag, thumbnail: await thumbnailUrl(dir) });
}
- out.push({ name: entry.name, dir, description, tag, thumbnail: await thumbnailUrl(dir) });
}
return out;
}
-/** Copy a template into `<location>/<name>`, stamp the manifest name, return the new root. */
+/** Copy a template into `<location>/<name>`, stamp the manifest name, return the new root.
+ * Transient state (`.esengine` staging, node_modules, …) stays behind. */
export async function createFromTemplate(templateDir: string, location: string, name: string): Promise<string> {
const dest = path.join(location, name);
if (existsSync(dest)) throw new Error(`a folder already exists at ${dest}`);
- await cp(templateDir, dest, { recursive: true });
+ await cp(templateDir, dest, {
+ recursive: true,
+ filter: (src) => !isTransientProjectPath(path.relative(templateDir, src)),
+ });
const manifestPath = path.join(dest, PROJECT_MANIFEST_FILE);
const m = parseManifest(JSON.parse(await readFile(manifestPath, 'utf8')));
m.name = name;
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index fdd3c2dc4..85d315e5d 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -82,7 +82,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
// main.mjs > Electron main
// preload.mjs > Preload scripts
// dist/ > Vite renderer build
-// public/ > static assets (wasm, sdk, examples) in dev
+// public/ > static assets (wasm, sdk, verify scenes) in dev
process.env.APP_ROOT = path.join(__dirname, '..');
// Automation gets its own profile dir — never fight the live editor over cache locks.
diff --git a/desktop/src/launcher/Launcher.tsx b/desktop/src/launcher/Launcher.tsx
index bc96654fd..6f50bcb52 100644
--- a/desktop/src/launcher/Launcher.tsx
+++ b/desktop/src/launcher/Launcher.tsx
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { useEffect, useMemo, useState } from 'react';
+import { Fragment, useEffect, useMemo, useState } from 'react';
import { ArrowRight, Clock, FolderOpen, LayoutGrid, Plus, Rows3, X } from 'lucide-react';
import { useEditorStore } from '@/store/editorStore';
import { ProjectStore } from '@/project/ProjectStore';
@@ -210,7 +210,7 @@ function RecentView({
function NewView({ onCreated }: { onCreated: () => void }) {
const [templates, setTemplates] = useState<TemplateEntry[]>([]);
- const [selected, setSelected] = useState<number | null>(null);
+ const [selected, setSelected] = useState<string | null>(null);
const [name, setName] = useState('');
const [location, setLocation] = useState('');
const [busy, setBusy] = useState(false);
@@ -226,11 +226,19 @@ function NewView({ onCreated }: { onCreated: () => void }) {
};
}, []);
- const tpl = selected != null ? templates[selected] : null;
+ const tpl = selected != null ? templates.find((t) => t.dir === selected) ?? null : null;
- const pick = (i: number) => {
- setSelected(i);
- setName((n) => n || templates[i].name.toLowerCase().replace(/\s+/g, '-'));
+ // The gallery's group order (starters, then examples) is the list order —
+ // group labels only earn their space when both groups are present.
+ const starters = templates.filter((t) => t.kind === 'starter');
+ const examples = templates.filter((t) => t.kind !== 'starter');
+ const grouped = starters.length > 0 && examples.length > 0;
+
+ const pick = (t: TemplateEntry) => {
+ setSelected(t.dir);
+ // Suggest a folder name: a starter is a blank slate ("my-project"), a
+ // sample keeps its own name so the copy stays recognizable.
+ setName((n) => n || (t.kind === 'starter' ? 'my-project' : t.name.toLowerCase().replace(/\s+/g, '-')));
};
const browse = () => {
@@ -262,25 +270,36 @@ function NewView({ onCreated }: { onCreated: () => void }) {
</header>
{templates.length === 0 ? (
<div className="lc-empty">
- <p>No templates found.</p>
+ <p>The bundled templates are missing.</p>
+ <p className="lc-empty__hint">Reinstalling the editor should restore them.</p>
</div>
) : (
<div className="proj-grid">
- {templates.map((t, i) => (
- <button
- key={t.dir}
- type="button"
- className={`proj-card proj-card--template${selected === i ? ' is-selected' : ''}`}
- onClick={() => pick(i)}
- >
- <Thumb label={t.name} src={t.thumbnail} />
- <div className="proj-card__body">
- <span className="proj-card__name">{t.name}</span>
- {t.description && <span className="proj-card__desc">{t.description}</span>}
- </div>
- {t.tag && <span className="proj-card__tag mono">{t.tag}</span>}
- </button>
- ))}
+ {[
+ { label: 'Starters', items: starters },
+ { label: 'Examples', items: examples },
+ ].map(({ label, items }) =>
+ items.length === 0 ? null : (
+ <Fragment key={label}>
+ {grouped && <h2 className="lc-group">{label}</h2>}
+ {items.map((t) => (
+ <button
+ key={t.dir}
+ type="button"
+ className={`proj-card proj-card--template${selected === t.dir ? ' is-selected' : ''}`}
+ onClick={() => pick(t)}
+ >
+ <Thumb label={t.name} src={t.thumbnail} />
+ <div className="proj-card__body">
+ <span className="proj-card__name">{t.name}</span>
+ {t.description && <span className="proj-card__desc">{t.description}</span>}
+ </div>
+ {t.tag && <span className="proj-card__tag mono">{t.tag}</span>}
+ </button>
+ ))}
+ </Fragment>
+ ),
+ )}
</div>
)}
</div>
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index 2ca583561..a0c5a14e3 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -146,11 +146,24 @@ export interface ProjectManifest {
export interface TemplateEntry {
name: string;
dir: string;
+ /** Which gallery group the template belongs to: a bundled blank-slate
+ * starter, or one of the sample projects. */
+ kind: 'starter' | 'example';
description?: string;
tag?: string;
thumbnail?: string;
}
+// Per-machine / derived state that must never travel when a project directory
+// is copied as a template: the editor restages `.esengine` (typings, caches,
+// workspace) on open, and the rest is tooling output.
+const TEMPLATE_TRANSIENT = new Set([WORKSPACE_DIR, 'node_modules', 'dist', '.DS_Store', 'Thumbs.db']);
+
+/** True if a template-relative path is transient state (excluded from template copies). */
+export function isTransientProjectPath(rel: string): boolean {
+ return rel.split(/[\\/]/).some((seg) => TEMPLATE_TRANSIENT.has(seg));
+}
+
/** Editor-local, transient state (`.esengine/workspace.json`; gitignored). */
export interface WorkspaceState {
lastOpenedScene?: string;
@@ -321,8 +334,3 @@ export const DEFAULT_SCRIPTS: Required<ProjectScripts> = {
export function resolveScripts(manifest: Pick<ProjectManifest, 'scripts'>): Required<ProjectScripts> {
return { ...DEFAULT_SCRIPTS, ...(manifest.scripts ?? {}) };
}
-
-/** A fresh manifest for `new project`. */
-export function defaultManifest(name: string): ProjectManifest {
- return { formatVersion: PROJECT_FORMAT_VERSION, name, defaultScene: 'assets/scenes/main.esscene' };
-}
diff --git a/desktop/src/theme/launcher.css b/desktop/src/theme/launcher.css
index 4e899262e..41898109d 100644
--- a/desktop/src/theme/launcher.css
+++ b/desktop/src/theme/launcher.css
@@ -482,6 +482,19 @@
align-items: flex-start;
gap: 0;
}
+/* Gallery group label — a full grid row, in the launcher's micro-label voice. */
+.lc-group {
+ grid-column: 1 / -1;
+ margin: 6px 0 -6px;
+ font-size: var(--fs-2xs);
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.08em;
+ color: var(--text-faint);
+}
+.lc-group:first-child {
+ margin-top: 0;
+}
.lc-create {
width: 296px;
@@ -611,6 +624,11 @@
color: var(--text-dim);
font-size: var(--fs-md);
}
+.lc-empty__hint {
+ margin: -8px 0 0;
+ font-size: var(--fs-sm);
+ color: var(--text-faint);
+}
/* One quiet page-load moment; off when reduced motion is requested. */
@media (prefers-reduced-motion: no-preference) {
diff --git a/desktop/templates/blank/.gitignore b/desktop/templates/blank/.gitignore
new file mode 100644
index 000000000..359472ac2
--- /dev/null
+++ b/desktop/templates/blank/.gitignore
@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+.esengine/cache/
diff --git a/desktop/templates/blank/assets/scenes/main.esscene b/desktop/templates/blank/assets/scenes/main.esscene
new file mode 100644
index 000000000..6d374d4ff
--- /dev/null
+++ b/desktop/templates/blank/assets/scenes/main.esscene
@@ -0,0 +1,30 @@
+{
+ "version": "1.0",
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": { "x": 0, "y": 0, "z": 10 }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/templates/blank/assets/scenes/main.esscene.meta b/desktop/templates/blank/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..2ba514059
--- /dev/null
+++ b/desktop/templates/blank/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "9d9b6178-75e7-4ae5-8cc4-1c435f7056e3",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/desktop/templates/blank/project.esproject b/desktop/templates/blank/project.esproject
new file mode 100644
index 000000000..e0ff2a017
--- /dev/null
+++ b/desktop/templates/blank/project.esproject
@@ -0,0 +1,12 @@
+{
+ "formatVersion": "1",
+ "name": "Blank",
+ "description": "An empty scene with a camera — start from nothing.",
+ "version": "0.1.0",
+ "defaultScene": "assets/scenes/main.esscene",
+ "designResolution": {
+ "width": 800,
+ "height": 600
+ },
+ "spineVersion": "none"
+}
diff --git a/desktop/templates/blank/src/components.ts b/desktop/templates/blank/src/components.ts
new file mode 100644
index 000000000..fee09de68
--- /dev/null
+++ b/desktop/templates/blank/src/components.ts
@@ -0,0 +1,3 @@
+// Declare your components here with defineComponent / defineTag. The editor
+// imports only this module to read component schemas — keep startup code out.
+export {};
diff --git a/desktop/templates/blank/src/main.ts b/desktop/templates/blank/src/main.ts
new file mode 100644
index 000000000..1b5e32a78
--- /dev/null
+++ b/desktop/templates/blank/src/main.ts
@@ -0,0 +1,3 @@
+// Game entry — runs when the scene plays. Register systems here, e.g.
+// addSystemToSchedule(Schedule.Update, mySystem).
+import './components';
diff --git a/desktop/templates/blank/tsconfig.json b/desktop/templates/blank/tsconfig.json
new file mode 100644
index 000000000..0a8528b29
--- /dev/null
+++ b/desktop/templates/blank/tsconfig.json
@@ -0,0 +1,22 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "outDir": "./dist",
+ "rootDir": ".",
+ "baseUrl": ".",
+ "paths": {
+ "esengine": ["./.esengine/sdk/index.d.ts"],
+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"],
+ "@esengine/editor": ["./.esengine/editor/index.d.ts"]
+ }
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules"]
+}
diff --git a/desktop/tests/templates.test.ts b/desktop/tests/templates.test.ts
new file mode 100644
index 000000000..2d65388c0
--- /dev/null
+++ b/desktop/tests/templates.test.ts
@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { parseManifest, resolveLayout, resolveScripts, isTransientProjectPath, PROJECT_MANIFEST_FILE } from '@/project/format';
+
+// The bundled starter templates (shipped to resources/templates by
+// electron-builder) — every one must stay a complete, openable project:
+// this is what guarantees "New project" always works in a packaged editor.
+const TEMPLATES_ROOT = path.resolve(__dirname, '../templates');
+
+describe('bundled starter templates', () => {
+ const starters = readdirSync(TEMPLATES_ROOT, { withFileTypes: true })
+ .filter((e) => e.isDirectory())
+ .map((e) => e.name);
+
+ it('ships at least the blank starter', () => {
+ expect(starters).toContain('blank');
+ });
+
+ it.each(starters)('%s is a complete project', (name) => {
+ const dir = path.join(TEMPLATES_ROOT, name);
+ const manifest = parseManifest(
+ JSON.parse(readFileSync(path.join(dir, PROJECT_MANIFEST_FILE), 'utf8')),
+ );
+
+ // The default scene must exist and carry an active camera — a template
+ // that opens onto a black, cameraless viewport is not a starting point.
+ expect(manifest.defaultScene).toBeTruthy();
+ const scenePath = path.join(dir, manifest.defaultScene!);
+ expect(existsSync(scenePath)).toBe(true);
+ const scene = JSON.parse(readFileSync(scenePath, 'utf8')) as {
+ entities: Array<{ components: Array<{ type: string; data?: Record<string, unknown> }> }>;
+ };
+ const cameras = scene.entities.flatMap((e) => e.components).filter((c) => c.type === 'Camera');
+ expect(cameras.some((c) => c.data?.isActive === true)).toBe(true);
+
+ // Script entry points (schema extraction + play-realm bundle entry).
+ const scripts = resolveScripts(manifest);
+ expect(existsSync(path.join(dir, scripts.register))).toBe(true);
+ expect(existsSync(path.join(dir, scripts.main))).toBe(true);
+
+ // Layout dirs referenced by the manifest resolve inside the template.
+ const layout = resolveLayout(manifest);
+ expect(manifest.defaultScene!.startsWith(layout.scenes)).toBe(true);
+ });
+});
+
+describe('isTransientProjectPath (template-copy filter)', () => {
+ it('excludes per-machine and derived trees at any depth', () => {
+ expect(isTransientProjectPath('.esengine')).toBe(true);
+ expect(isTransientProjectPath('.esengine/sdk/index.d.ts')).toBe(true);
+ expect(isTransientProjectPath(String.raw`.esengine\workspace.json`)).toBe(true);
+ expect(isTransientProjectPath('node_modules/esengine/package.json')).toBe(true);
+ expect(isTransientProjectPath('dist/js/main.js')).toBe(true);
+ expect(isTransientProjectPath('.DS_Store')).toBe(true);
+ expect(isTransientProjectPath('assets/Thumbs.db')).toBe(true);
+ });
+
+ it('keeps project content, including the copy root itself', () => {
+ expect(isTransientProjectPath('')).toBe(false);
+ expect(isTransientProjectPath('project.esproject')).toBe(false);
+ expect(isTransientProjectPath('assets/scenes/main.esscene')).toBe(false);
+ expect(isTransientProjectPath(String.raw`assets\textures\logo.png`)).toBe(false);
+ expect(isTransientProjectPath('src/main.ts')).toBe(false);
+ expect(isTransientProjectPath('thumbnail.png')).toBe(false);
+ expect(isTransientProjectPath('.gitignore')).toBe(false);
+ });
+});