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(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.mdindex 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/desktopindex ef180a824..d99ff295f 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit ef180a82444d3a8d09f28d13816565d4af0add91+Subproject commit d99ff295f62c8fafec1b91643896a1cabd9a54c0diff --git a/docs/astro/src/content/docs/getting-started/installation.mdx b/docs/astro/src/content/docs/getting-started/installation.mdxindex 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.mdxindex 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.mjsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mjsindex 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":