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(pipeline): a project can be made from a template on the command line, by the same code as the editor's New project

yhh65b6431e95af
diff --git a/CHANGELOG.md b/CHANGELOG.md
index be70c6414..3aad7d74a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **Start a project from the command line.** `estella create <template> <dir> [--name]` makes a project from any starter or example, and `estella templates` lists them. The editor's New project gallery and the command line now share one implementation (`pipeline/src/project/scaffold.ts`), so both copy the same files and write the same `package.json` and `.gitignore`.
- **Clouds drawn from a coverage picture.** `skyAtmosphere` takes a Cloud Mask (`u_cloudMask`, with `u_cloudMaskTile` in kilometres of the cloud layer) and a second, higher one (`u_cloudMask2`): the clouds stand where the mask says and the noise only erodes them. The shadow the clouds cast and the beams of `heightFog`'s `cloudShade` read the same masks, which the fog takes from the sky. Terrain & Water uses the two the art made.
- **A Display LUT.** The `displayLut` effect reads a look off a 1024x32 lookup table by the picture as the display will show it, in the last pass, after the output transform and the transfer function: the place a look authored against the finished image belongs, and one no effect in the chain can be, since they run on scene values before the curve. It is a variant of the pass that was running, one texture read and no pass of its own, and `PostProcessStack.setDisplayLut(texture, amount)` is the same thing in code. The last pass now reads its parameters off the reflected layout as a material does, and the copies it makes share them.
- **Light beams that follow the clouds.** `heightFog` has a `cloudShade`: its volumetric light marches the sun's ray up through the cloud layer of a `skyAtmosphere` whose clouds cast shadows (the same density the sky draws, fixed to the world and drifting with its wind), so a gap in the clouds is a beam in the air and what they cover is dark, whichever way the camera looks. `volumeRange` may now be as long as a million units, for beams through clouds kilometres up. The sky's clouds are copied onto the fog each frame, and an effect's uniform may be `internal`, which an inspector does not list.
diff --git a/desktop b/desktop
index ef180a824..d99ff295f 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit ef180a82444d3a8d09f28d13816565d4af0add91
+Subproject commit d99ff295f62c8fafec1b91643896a1cabd9a54c0
diff --git a/docs/astro/src/content/docs/getting-started/installation.mdx b/docs/astro/src/content/docs/getting-started/installation.mdx
index bc72d448c..9a105aa57 100644
--- a/docs/astro/src/content/docs/getting-started/installation.mdx
+++ b/docs/astro/src/content/docs/getting-started/installation.mdx
@@ -74,3 +74,17 @@ import { Tabs, TabItem, Steps, Aside } from '@astrojs/starlight/components';
for the full build reference.
</TabItem>
</Tabs>
+
+## Start a project from the command line
+
+The editor's New project gallery and the command line make a project the same way, from the same templates, so a project can be started
+without opening the editor, in a script, or on a build machine:
+
+```bash
+node pipeline/bin/estella.mjs templates # what there is to start from
+node pipeline/bin/estella.mjs create 3d-starter ./my-game --name "My Game"
+node pipeline/bin/estella.mjs export ./my-game # a web build, no editor
+```
+
+`create` copies the template into the folder, names the project, and adds the `package.json` and `.gitignore` every project has. Open the
+project in the editor once to stage the SDK types its `tsconfig.json` points at; exporting needs nothing more.
diff --git a/docs/astro/src/content/docs/zh-cn/getting-started/installation.mdx b/docs/astro/src/content/docs/zh-cn/getting-started/installation.mdx
index c4d119c72..a23f6ed63 100644
--- a/docs/astro/src/content/docs/zh-cn/getting-started/installation.mdx
+++ b/docs/astro/src/content/docs/zh-cn/getting-started/installation.mdx
@@ -69,3 +69,15 @@ import { Tabs, TabItem, Steps, Aside } from '@astrojs/starlight/components';
[CONTRIBUTING.md](https://github.com/esengine/estella/blob/master/CONTRIBUTING.md)。
</TabItem>
</Tabs>
+
+## 用命令行新建项目
+
+编辑器里的"新建项目"画廊和命令行用同一份实现、同一批模板创建项目,所以不打开编辑器、在脚本里或在构建机上也能开一个项目:
+
+```bash
+node pipeline/bin/estella.mjs templates # 看有哪些模板
+node pipeline/bin/estella.mjs create 3d-starter ./my-game --name "My Game"
+node pipeline/bin/estella.mjs export ./my-game # 不开编辑器导出网页版
+```
+
+`create` 把模板复制进文件夹、写好项目名,并补上每个项目都有的 `package.json` 和 `.gitignore`。在编辑器里打开一次项目,会暂存 `tsconfig.json` 指向的 SDK 类型;只导出的话不需要这一步。
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index d07ececa8..270db496d 100644
--- a/pipeline/bin/estella.mjs
+++ b/pipeline/bin/estella.mjs
@@ -12,7 +12,9 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
const PIPELINE = path.join(HERE, '..');
const REPO = path.join(PIPELINE, '..');
-const USAGE = `usage: node pipeline/bin/estella.mjs export <projectDir> [options]
+const USAGE = `usage: node pipeline/bin/estella.mjs create <template> <dir> [--name <project name>]
+ node pipeline/bin/estella.mjs templates
+ node pipeline/bin/estella.mjs export <projectDir> [options]
node pipeline/bin/estella.mjs import-model <file.gltf|file.glb|file.fbx> [outDir]
[--project <dir>] [--scale <n>]
[--specular-map color|orm] [--lightmap-uv] [--lods <0-3>]
@@ -83,6 +85,15 @@ function parseArgs(argv) {
console.log(USAGE);
process.exit(0);
}
+ if (command === 'templates') return { command };
+ if (command === 'create') {
+ const named = rest.indexOf('--name');
+ if (!projectDir || !rest[0] || rest[0].startsWith('--')) {
+ console.error('create requires a template and a folder: node pipeline/bin/estella.mjs create <template> <dir> [--name <project name>]');
+ process.exit(2);
+ }
+ return { command, template: projectDir, dest: path.resolve(rest[0]), name: named >= 0 ? rest[named + 1] : undefined };
+ }
if (command === 'bake-scene') {
if (!projectDir) {
console.error(USAGE);
@@ -706,6 +717,30 @@ function engineRuntimeDir(platform) {
const opts = parseArgs(process.argv.slice(2));
+// The editor's New Project gallery and these two are one implementation (src/project/scaffold.ts): the same templates, the same files.
+if (opts.command === 'templates' || opts.command === 'create') {
+ const { mod, cleanup } = await loadPipeline(path.join(PIPELINE, 'src/project/scaffold.ts'), 'scaffold.mjs');
+ try {
+ const roots = [{ root: path.join(REPO, 'templates'), kind: 'starter' }, { root: path.join(REPO, 'examples'), kind: 'example' }];
+ const found = await mod.listTemplates(roots);
+ if (opts.command === 'templates') {
+ const width = Math.max(...found.map((t) => path.basename(t.dir).length));
+ for (const t of found) console.log(`${path.basename(t.dir).padEnd(width)} ${t.kind.padEnd(7)} ${t.description ?? t.name}`);
+ } else {
+ const template = found.find((t) => path.basename(t.dir) === opts.template);
+ if (!template) throw new Error(`no template "${opts.template}"; \`templates\` lists them`);
+ const root = await mod.createFromTemplate(template.dir, path.dirname(opts.dest), path.basename(opts.dest), opts.name ?? path.basename(opts.dest));
+ console.log(`created ${path.relative(process.cwd(), root) || root} from ${opts.template}`);
+ console.log('Open it in the Estella editor once (it stages the SDK types the project\'s tsconfig points at), or export it with:');
+ console.log(` node pipeline/bin/estella.mjs export ${path.relative(process.cwd(), root) || root}`);
+ }
+ } catch (error) {
+ console.error(error.message);
+ process.exitCode = 1;
+ } finally { cleanup(); }
+ process.exit(process.exitCode ?? 0);
+}
+
if (opts.command === 'package-openpaas') {
const { mod, cleanup } = await loadPipeline(path.join(PIPELINE, 'src/export/openpaasPackage.ts'), 'openpaasPackage.mjs');
try {
diff --git a/pipeline/src/project/scaffold.ts b/pipeline/src/project/scaffold.ts
new file mode 100644
index 000000000..dd38b2f77
--- /dev/null
+++ b/pipeline/src/project/scaffold.ts
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Making a new project out of a template: the files every project gets, and the copy.
+ *
+ * One implementation for the editor's New Project gallery and the command line's `create`, because two would
+ * disagree about what a fresh project holds. The scaffold files are generated at creation rather than kept in
+ * each template, because there are forty-odd templates (the blank starters and every example) and a copy in
+ * each is a copy that drifts: the blank one's `.gitignore` listed `dist/` while every export writes
+ * `dist-<platform>/`, so a packaged game landed in git.
+ *
+ * `package.json` is here because a project's scripts are bundled with esbuild, which resolves npm dependencies
+ * out of the project's own `node_modules`: `npm install <a-library>` works and the library ships with the game,
+ * on every target. Without a package.json that starts with an `npm init` nobody would guess is a prerequisite.
+ *
+ * Pure Node (fs), no electron, so it runs under the command line and under test.
+ */
+import { cp, readdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { PROJECT_MANIFEST_FILE, isTransientProjectPath, parseManifest, type TemplateEntry } from './format';
+
+/**
+ * An npm-legal package name from a project's display name: "My Game" is a fine project name and an illegal package name.
+ * A name with nothing legal in it still yields an installable one.
+ */
+export function npmPackageName(displayName: string): string {
+ const slug = displayName
+ .toLowerCase()
+ .replace(/[^a-z0-9._-]+/g, '-')
+ .replace(/^[._-]+/, '')
+ .replace(/[._-]+$/, '')
+ .slice(0, 214);
+ return slug || 'estella-game';
+}
+
+export const PROJECT_GITIGNORE = `node_modules/
+
+# Export output — the Package dialog writes dist-<platform>/ per target.
+dist/
+dist-*/
+
+# Editor-managed staging: the SDK types mirror, the play-realm build and the
+# workspace are regenerated every time the editor opens the project.
+.esengine/
+
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+`;
+
+/**
+ * Write the scaffold into an already-created project directory.
+ *
+ * Existing files are left alone: a template that ships its own on purpose keeps
+ * it, and running this over a project twice changes nothing.
+ */
+export async function scaffoldProjectFiles(dest: string, name: string): Promise<void> {
+ const packageJson = path.join(dest, 'package.json');
+ if (!existsSync(packageJson)) {
+ // `private` so an accidental `npm publish` cannot reach the registry; `type: module` to match the tsconfig's ESM.
+ // No dependencies or scripts: the editor builds the project, and npm is here so installing a library works.
+ await writeFile(packageJson, `${JSON.stringify({
+ name: npmPackageName(name),
+ version: '0.0.0',
+ private: true,
+ type: 'module',
+ }, null, 2)}\n`);
+ }
+ const gitignore = path.join(dest, '.gitignore');
+ if (!existsSync(gitignore)) await writeFile(gitignore, PROJECT_GITIGNORE);
+}
+
+/** A directory of templates and the gallery group its entries belong to. */
+export interface TemplateRoot {
+ root: string;
+ kind: TemplateEntry['kind'];
+}
+
+/**
+ * Every project directly under the roots, in the roots' order. A name a root listed first is not listed again by a later one, so an
+ * example never shadows the starter of the same name. An entry whose manifest cannot be read is still listed, by its folder's name.
+ */
+export async function listTemplates(roots: readonly TemplateRoot[]): Promise<TemplateEntry[]> {
+ const out: TemplateEntry[] = [];
+ const seen = new Set<string>();
+ for (const { root, kind } of roots) {
+ 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, description: string | undefined, 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 {
+ // listed by its folder's name
+ }
+ out.push({ name, dir, kind, description, tag });
+ }
+ }
+ return out;
+}
+
+/**
+ * Copies a template into the folder `<location>/<name>`, stamps the manifest with `displayName` (the folder's name unless said) and writes the
+ * scaffold; returns the new root.
+ * Transient state (`.esengine` staging, node_modules and the like) stays behind.
+ */
+export async function createFromTemplate(templateDir: string, location: string, name: string, displayName = name): 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,
+ 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 = displayName;
+ await writeFile(manifestPath, `${JSON.stringify(m, null, 2)}\n`);
+ await scaffoldProjectFiles(dest, displayName);
+ return dest;
+}
diff --git a/pipeline/tests/project-scaffold.test.ts b/pipeline/tests/project-scaffold.test.ts
new file mode 100644
index 000000000..8c99e20bc
--- /dev/null
+++ b/pipeline/tests/project-scaffold.test.ts
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A new project made from a template: the one implementation the editor's gallery and the command line's `create` share.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { createFromTemplate, listTemplates, npmPackageName } from '../src/project/scaffold';
+
+let dir = '';
+beforeEach(() => { dir = mkdtempSync(path.join(tmpdir(), 'estella-scaffold-')); });
+afterEach(() => { rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });
+
+const template = (root: string, id: string, manifest: object | string): string => {
+ const t = path.join(root, id);
+ mkdirSync(path.join(t, 'src'), { recursive: true });
+ writeFileSync(path.join(t, 'project.esproject'), typeof manifest === 'string' ? manifest : JSON.stringify({ formatVersion: '1', name: id, ...manifest }));
+ writeFileSync(path.join(t, 'src/main.ts'), 'export {};\n');
+ return t;
+};
+
+describe('listing templates', () => {
+ it('lists the projects under each root in order, and does not list a name twice', async () => {
+ const starters = path.join(dir, 'starters'), examples = path.join(dir, 'examples');
+ template(starters, 'blank', { description: 'Nothing.', tag: 'Starter' });
+ template(examples, 'blank', { description: 'Shadowed.' });
+ template(examples, 'bistro', { description: 'A street.' });
+ mkdirSync(path.join(examples, 'not-a-project'));
+ const found = await listTemplates([{ root: starters, kind: 'starter' }, { root: examples, kind: 'example' }, { root: path.join(dir, 'missing'), kind: 'example' }]);
+ expect(found.map((t) => [path.basename(t.dir), t.kind, t.description])).toEqual([['blank', 'starter', 'Nothing.'], ['bistro', 'example', 'A street.']]);
+ });
+
+ it('lists a project whose manifest cannot be read, by its folder\'s name', async () => {
+ const root = path.join(dir, 'starters');
+ template(root, 'broken', '{ not json');
+ expect((await listTemplates([{ root, kind: 'starter' }])).map((t) => t.name)).toEqual(['broken']);
+ });
+});
+
+describe('creating a project', () => {
+ it('copies the template, names the manifest, and writes the files every project has', async () => {
+ const t = template(path.join(dir, 'starters'), 'blank', {});
+ const root = await createFromTemplate(t, path.join(dir, 'games'), 'my-game', 'My Game');
+ expect(root).toBe(path.join(dir, 'games', 'my-game'));
+ expect(JSON.parse(readFileSync(path.join(root, 'project.esproject'), 'utf8')).name).toBe('My Game');
+ expect(JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')).name).toBe('my-game');
+ expect(readFileSync(path.join(root, '.gitignore'), 'utf8')).toContain('dist-*/');
+ expect(existsSync(path.join(root, 'src/main.ts'))).toBe(true);
+ });
+
+ it('names the project after its folder unless told otherwise, and leaves transient state behind', async () => {
+ const t = template(path.join(dir, 'starters'), 'blank', {});
+ mkdirSync(path.join(t, '.esengine'));
+ mkdirSync(path.join(t, 'node_modules'));
+ const root = await createFromTemplate(t, path.join(dir, 'games'), 'plain');
+ expect(JSON.parse(readFileSync(path.join(root, 'project.esproject'), 'utf8')).name).toBe('plain');
+ expect(existsSync(path.join(root, '.esengine'))).toBe(false);
+ expect(existsSync(path.join(root, 'node_modules'))).toBe(false);
+ });
+
+ it('refuses a folder that is already there', async () => {
+ const t = template(path.join(dir, 'starters'), 'blank', {});
+ await createFromTemplate(t, path.join(dir, 'games'), 'taken');
+ await expect(createFromTemplate(t, path.join(dir, 'games'), 'taken')).rejects.toThrow(/already exists/);
+ });
+});
+
+describe('package names', () => {
+ it('are npm-legal whatever the project is called', () => {
+ expect(npmPackageName('My Game')).toBe('my-game');
+ expect(npmPackageName('星邻')).toBe('estella-game');
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index c1b400c8e..653a60f23 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2870,6 +2870,8 @@ export const NOTED = {
{"internal":"Restores the refusal a cull-only group had lost; nothing a creator could use changed."},
"fix(editor-checks): the texture handle sample is taken again until its frame is drawn":
{"internal":"A test race."},
+ "feat(pipeline): a project can be made from a template on the command line, by the same code as the editor's New project":
+ {"note":"Start a project from the command line."},
"feat(water): two tiled, scrolling detail normal maps give the surface its sparkle":
{"note":"Sparkle on the water."},
"fix(lod): a LODGroup with only a cull size is no longer ignored":