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.

docs(comments): cut the narrative back to the convention

yhhe7407a753094
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 521dad9bf..e18ca1f91 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -797,9 +797,8 @@ export class SceneCommandsImpl {
/** Duplicate a whole selection as ONE undo step. Returns the new source ids. */
duplicateEntities(ids: readonly EntityId[]): EntityId[] {
if (ids.length === 0) return [];
- // Roots only: duplicateEntity copies a whole SUBTREE, so a selection holding a
- // parent and one of its children produced that child twice — once inside the
- // parent's copy, once beside it.
+ // Roots only: duplicateEntity copies a whole subtree, so a parent and its
+ // child in one selection would copy that child twice.
const roots = this.model.selectionRoots(ids);
if (roots.length === 1) {
const d = this.duplicateEntity(roots[0]);
diff --git a/desktop/src/engine/SceneModel.ts b/desktop/src/engine/SceneModel.ts
index 3632b80a4..b2ee066ae 100644
--- a/desktop/src/engine/SceneModel.ts
+++ b/desktop/src/engine/SceneModel.ts
@@ -518,13 +518,8 @@ export class SceneModelImpl {
/**
* The entities of a selection that nothing else in it contains — its roots.
*
- * A selection made by dragging or shift-clicking down the Outliner routinely
- * holds a parent AND some of its children, and almost every operation means the
- * subtree rather than each entry: duplicating both copies the child twice, and a
- * prefab of both is a prefab of the parent. Whoever asks "what did they actually
- * pick" needs this, and asking it by hand is a parent-walk each time.
- *
- * Order follows the input, so a caller's notion of "the first one" survives.
+ * A selection routinely holds a parent AND some of its children, and operations
+ * that act on a whole subtree must run once per root, not once per entry.
*/
selectionRoots(ids: Iterable<number>): number[] {
const selected = new Set(ids);
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 7c274eb4d..5da7e37dd 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -118,20 +118,11 @@ function documentState(): { kind: 'scene' | 'prefab'; path: string | null; name:
}
/**
- * Refuse a document swap that would throw away unsaved work, unless the caller
- * says to throw it away.
+ * Refuse a document swap that would discard unsaved work, unless the caller opts
+ * in. Every door that replaces the open document goes through this, and the
+ * answer comes from the registry — the scene AND every open asset editor.
*
- * Every door that replaces the open document asks this ONE question, and the
- * answer comes from the registry — the scene AND every open asset editor — never
- * from one document. discardGuard states that rule for the UI prompts ("not just
- * the scene's EditorHistory"), and four doors here each restated it by hand until
- * one of them drifted: `openScene` asked EditorHistory alone, so opening a scene
- * over an unsaved tileset or material graph was refused through open_asset and
- * waved through here.
- *
- * A person gets a prompt for this. A driver gets a refusal, because a modal with
- * nobody to answer it never resolves — so discarding is something the caller says
- * out loud instead.
+ * A refusal rather than a prompt: a modal here has nobody to answer it.
*/
function requireDiscardable(discardChanges: boolean, what: string): void {
if (discardChanges || !DirtyRegistry.isDirty()) return;
diff --git a/desktop/src/panels/inspector/componentDecorators.tsx b/desktop/src/panels/inspector/componentDecorators.tsx
index 3f7dccc49..8ab9f68e6 100644
--- a/desktop/src/panels/inspector/componentDecorators.tsx
+++ b/desktop/src/panels/inspector/componentDecorators.tsx
@@ -1,30 +1,16 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file componentDecorators.tsx — the ONE door for per-component inspector UI.
+ * @file componentDecorators.tsx — the one door for per-component inspector UI.
+ * @brief Extra UI a component gets beyond its reflected fields: the UINode anchor
+ * grid, the collider shape switch, the "put me under a Canvas" action.
*
- * Most of what the Details panel draws is derived: the component registry says a
- * field is a vec2 or an enum, and a control renders it. A handful of components
- * need more than their fields — a UINode wants its anchor grid, a collider wants
- * a shape switch, an orphaned UI element wants a one-click "put me under a
- * Canvas". That extra is what a decorator is.
+ * Built-ins register under owner `'core'` like every other contribution, so the
+ * panel never branches on a component name.
*
- * It exists because there were TWO ways to add it. Plugins registered through
- * `inspectorRegistry`; the editor's own hardcoded a chain of
- * `comp.name === 'UINode' ? … : comp.name === 'FlexContainer' ? …` in the panel
- * body, directly above the element that renders the plugin sections. Fifteen other
- * registries in this editor take built-ins under owner `'core'` for exactly the
- * reason ContributionRegistry states — "there is no separate plugin API to drift
- * from" — and the inspector was the one that did not, so it drifted: the two
- * inspector bodies (edit and the live Game panel) grew DIFFERENT chains, and one
- * of them shipped an edit-mode action wired to a realm runtime id.
- *
- * A decorator declares which surfaces it serves. That is not bookkeeping: the Game
- * inspector selects by REALM runtime id, a different id space from the edit
- * model's source ids ("never mixed", says PlayInspect), so a decorator that walks
- * SceneModel or runs SceneCommands is not merely useless there — it reads a
- * foreign id as if it were local. Edit-only is therefore the default, and a
- * decorator opts in to `'play'` deliberately.
+ * A decorator declares its `surfaces`, defaulting to edit-only: the Game
+ * inspector selects by realm runtime id, which is a different id space from the
+ * edit model's source ids, so one that walks SceneModel would misread it.
*/
import { Fragment, useEffect, useState, useSyncExternalStore } from 'react';
@@ -612,10 +598,9 @@ export interface ComponentDecorator {
}
/**
- * Extra UI for the ENTITY rather than one of its components, rendered above the
- * component sections. It is a separate kind because its trigger is a predicate over
- * the whole component set — the Controllers strip appears for a UI entity, which is
- * one carrying UINode OR Canvas, and must appear once for one carrying both.
+ * Extra UI for the ENTITY rather than one component, rendered above the sections.
+ * A separate kind because its trigger is a predicate over the whole component set,
+ * and it must appear once for an entity matching it twice.
*/
export interface EntityDecorator {
id: string;
@@ -651,14 +636,12 @@ const BUILTIN_COMPONENT_DECORATORS: ComponentDecorator[] = [
ownedFields: () => FLEX_WIDGET_OWNED_FIELDS,
},
{
- // A boxless Text anchors to the origin, so align/verticalAlign resolve against
- // nothing. Edit-only: it creates a Canvas and reparents through SceneCommands.
+ // Edit-only: it creates a Canvas and reparents through SceneCommands.
id: 'core.text.layout-box',
component: 'Text',
action: ({ entities, comp }) => (entities.length === 1 ? textBoxAction(comp, entities[0]!) : undefined),
},
- // One per convertible collider: the shape switch converts the component itself,
- // so it belongs to each shape's section rather than to a shared "collider" idea.
+ // One per convertible collider: the switch converts the component itself.
...Object.keys(COMP_COLLIDER_SHAPE).map((component): ComponentDecorator => ({
id: `core.collider.shape.${component}`,
component,
@@ -705,10 +688,8 @@ export function entityDecorators(componentNames: readonly string[], surface: Ins
/**
* The rendered extra block for a component section, or undefined when none applies.
*
- * Fragments, not wrapper elements: every decorator body is block-level (`.anchor-block`,
- * `.collider-shape`) and the section's own CSS lays them out as its children. An element
- * in between — an inline `<span>` especially — reparents them into a new formatting
- * context and the block collapses.
+ * Fragments, not wrapper elements: decorator bodies are block-level and the section
+ * lays them out as its own children, so an element in between collapses them.
*/
export function decoratorExtra(ctx: DecoratorContext): ReactNode | undefined {
const parts = componentDecorators(ctx.comp.name, ctx.surface).filter((d) => d.render);
diff --git a/desktop/src/panels/inspector/controls.tsx b/desktop/src/panels/inspector/controls.tsx
index 4815cf811..bbc8b5257 100644
--- a/desktop/src/panels/inspector/controls.tsx
+++ b/desktop/src/panels/inspector/controls.tsx
@@ -1,21 +1,13 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file controls.tsx — one control per field TYPE, and nothing per component.
+ * @file controls.tsx
+ * @brief One control per field TYPE — vec2, enum, asset ref, gradient — and none
+ * per component: adding a component adds no code here.
*
- * These render an `InspectorField` by its `type` — a vec2, an enum, an asset ref,
- * a gradient. That vocabulary comes from the component registry, so a control here
- * serves every component that declares the type and none of them by name: adding a
- * component adds no code to this file.
- *
- * They lived inside Details.tsx, which made the panel the only thing that could
- * hold them — the decorators that a component registers cannot import a control out
- * of the panel that renders the decorators without a cycle. Splitting them out is
- * what lets the inspector have ONE door for per-component UI instead of two.
- *
- * A control never reaches for SceneCommands itself. Writes arrive as callbacks the
- * caller built (see `fieldWriter` in Details.tsx), so the same control serves the
- * undoable edit path and the live "Game" inspector that routes to the realm.
+ * A control never reaches for SceneCommands. Writes arrive as callbacks the
+ * caller built (`fieldWriter` in Details.tsx), so one control serves both the
+ * undoable edit path and the live Game inspector that routes to the realm.
*/
import { useMemo, useRef, useState, useSyncExternalStore } from 'react';
diff --git a/desktop/src/project/AssetRegistry.ts b/desktop/src/project/AssetRegistry.ts
index b11ad14f8..418ad978e 100644
--- a/desktop/src/project/AssetRegistry.ts
+++ b/desktop/src/project/AssetRegistry.ts
@@ -1,29 +1,13 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file AssetRegistry.ts — what the project's assets are, and where they live.
+ * @file AssetRegistry.ts
+ * @brief The project's asset database: uuid ↔ path, plus each asset's `.meta`
+ * importer block and content-minted type, from the asset scan.
*
- * Four lookup tables built from the `.meta` sidecars an asset scan finds: uuid to
- * path, path to uuid, and per-uuid the importer block and the type minted from the
- * file's own content. Everything that resolves a reference reads them — the
- * inspector's asset picker, the Content Browser's drag guard, the prefab loader,
- * the play manifest, the texture import path.
- *
- * They used to be four private Maps inside ProjectStore, whose other jobs are
- * opening a project, the scene document, prefab sessions and the settings
- * manifest. `pathToUuid` alone was read by fifteen of its methods, which is not
- * god-object coupling but the opposite: the asset database is a real shared
- * substrate, and it had no name. Eighteen files reached for ProjectStore when what
- * they wanted was a uuid.
- *
- * This owns the tables and answers questions about them. It does NOT scan — a scan
- * needs the open project, its root and its watcher, which belong to ProjectStore.
- * ProjectStore feeds the result in through {@link rebuild}; the direction is one
- * way, so a query never reaches back for a project.
- *
- * Load bookkeeping lives here too (which refs failed, which hot-loads have
- * started), because both are keyed by the same identities and answer the same
- * question a caller asks about a ref: is this thing actually there.
+ * Does NOT scan — that needs the open project, its root and its watcher, which
+ * belong to ProjectStore, which feeds results in through {@link rebuild}. The
+ * dependency runs one way, so a query never reaches back for a project.
*/
import { Assets, getEditorType, textureImportSettingsFrom, setTextureParams, setTextureSliceBorder, TextureFilter, TextureWrap } from 'esengine';
import { EngineHost } from '@/engine/EngineHost';
diff --git a/desktop/src/project/PrefabCache.ts b/desktop/src/project/PrefabCache.ts
index 6ab61c3dc..599284db9 100644
--- a/desktop/src/project/PrefabCache.ts
+++ b/desktop/src/project/PrefabCache.ts
@@ -1,24 +1,16 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file PrefabCache.ts — loaded `.esprefab` assets, and the synchronous resolver
- * the expansion needs.
+ * @file PrefabCache.ts
+ * @brief Loaded `.esprefab` content, and the synchronous resolver expansion needs.
*
- * Expanding a prefab instance is SYNCHRONOUS — `flattenPrefab` walks a variant's
- * base and every `nestedPrefab` in one pass and cannot await — while reading a
- * `.esprefab` off disk is not. The gap between those two facts is this cache: an
- * async load warms every dependency a prefab can reach, and the expansion then
- * resolves them out of memory.
+ * `flattenPrefab` walks a variant's base and every `nestedPrefab` in one pass and
+ * cannot await, so {@link load} warms every reachable dependency up front and
+ * {@link resolveSync} reads them out of memory.
*
- * Warming is why a plain memo will not do. {@link load} caches the prefab BEFORE
- * warming its dependencies, so a variant or nested reference that cycles back
- * terminates on the second visit instead of fetching forever.
- *
- * The cache is separate from {@link AssetRegistry} because it is a different kind
- * of thing: the registry says where an asset IS, from a scan; this holds asset
- * CONTENT, read on demand and invalidated per file when one changes. Their
- * lifetimes differ too — a rebuild of the lookup tables must not drop every
- * loaded prefab, which is exactly the distinction an incremental rescan turns on.
+ * Separate from {@link AssetRegistry}: that says where an asset is, from a scan;
+ * this holds content, invalidated per file. A lookup-table rebuild must not drop
+ * loaded prefabs, which is what an incremental rescan turns on.
*/
import { migratePrefabData, validateOverrides } from 'esengine';
import type { PrefabData, SceneData, PrefabOverride, StaleOverride } from 'esengine';
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 7c3af0f1b..f2a6a2b4d 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -178,12 +178,8 @@ class ProjectStoreImpl {
/** The latest scene preload result; the Reconciler resolver reads handles from
* it for entities recreated incrementally (duplicate / undo / play-stop). */
private lastAssetResult: PreloadResult | null = null;
- /** What the OPEN DOCUMENT looked like on disk the last time we read or wrote it —
- * a scene, or the `.esprefab` being edited in Prefab Mode. It answers one
- * question, "was that change ours", and it is per-document rather than
- * per-scene because both kinds are edited in the same world and overwritten by
- * the same Save. While it tracked only the scene, an external edit to a prefab
- * open in Prefab Mode was invisible and Save silently overwrote it. */
+ /** The open document as it last was on disk — a scene, or the `.esprefab` in
+ * Prefab Mode. Answers "was that change ours" for the disk-change reconcile. */
private diskText: string | null = null;
private diskPath: string | null = null;
/** A disk-change discard prompt is showing — don't stack another. */
@@ -672,16 +668,10 @@ class ProjectStoreImpl {
}
/**
- * A new, empty prefab: the entity the Create menu's "Empty" makes, as a
- * standalone asset.
+ * A new, empty prefab: the Create menu's "Empty" entity as a standalone asset.
*
- * Built from that entity SOURCE rather than a second definition of what an empty
- * entity is — the same reason the Canvas hosting a UI prefab is built from the
- * Canvas source. And run through `extractPrefab`, because that is what mints
- * entity identities: a source's in-memory prefab carries `prefabEntityId: '0'`,
- * the id every prefab had BEFORE stable ids, and an override aimed at `'0'` is
- * refused now — so writing one to disk would author an asset nothing can
- * customise.
+ * Goes through `extractPrefab` to mint entity ids — a source's in-memory prefab
+ * carries `prefabEntityId: '0'`, which the runtime spawn door now refuses.
*/
private async blankPrefab(name: string): Promise<PrefabData> {
const built = await sourceById('empty')?.build?.({ parent: null });
@@ -691,9 +681,7 @@ class ProjectStoreImpl {
return extractPrefab([entity as unknown as ExtractEntity], 0, name);
}
- /** Create a blank `.esprefab` under `destDir` — the Content Browser's New →
- * Prefab. An empty prefab is a starting point: double-click opens it in Prefab
- * Mode, where it is built up like a scene. */
+ /** Create a blank `.esprefab` under `destDir`; double-click opens it in Prefab Mode. */
async createPrefabFile(destDir: string, name = 'Prefab'): Promise<string> {
const content = JSON.stringify(await this.blankPrefab(name), null, 2) + '\n';
return window.estella.project.createAsset(destDir, 'prefab.esprefab', content, 'prefab');
@@ -1342,15 +1330,8 @@ class ProjectStoreImpl {
* immediately draggable. Non-destructive: the source entities are left as-is.
* Returns the new prefab's `@uuid:` ref, or null.
*
- * Takes a SELECTION, because that is what the Outliner has when someone asks.
- * A selection routinely holds a parent and some of its children, and the prefab
- * they mean is the parent — so it resolves to the selection's roots, and the
- * children come along as the subtree they already are.
- *
- * A prefab has exactly one root (`PrefabData.rootEntityId` is singular), so a
- * selection with SEVERAL roots is not a prefab. That is refused and said out
- * loud: it used to act on whichever entity happened to be right-clicked, which
- * silently produced a prefab of one of them.
+ * Takes a selection and resolves it to its roots. `PrefabData.rootEntityId` is
+ * singular, so several roots are refused rather than resolved arbitrarily.
*/
async createPrefabFromEntity(
target: number | readonly number[],
@@ -2116,24 +2097,11 @@ class ProjectStoreImpl {
}
/**
- * The open scene as a crash-recovery snapshot: its real target path + the exact
- * bytes {@link save} would write, WITHOUT persisting or marking saved. Null for
- * an untitled scene (no `currentScene` path to recover into).
- */
- /**
- * Everything the editor does to its open document, per KIND.
+ * Everything the editor does to its open document, one row per KIND.
*
- * A scene and a prefab are edited in the same world, by the same tools, through
- * the same undo history. What differs is which file they are and how they round
- * trip: a scene serializes the model and writes it; a prefab collapses the
- * flattened tree back against its base. Every caller wants the same four things,
- * and each of them used to ask `if (this.prefabSession)` in its own words.
- *
- * Twice that produced the same bug — an operation written for the scene, and the
- * prefab silently getting nothing: an external change went unnoticed because the
- * question was asked about `currentScene`, which is null here. One row per kind
- * makes that a compile error instead. A new per-document operation is a new
- * method on this interface, and TypeScript will not let it exist for one kind.
+ * A per-document operation added here must be implemented for both kinds or it
+ * does not compile — which is the point: writing one for the scene and leaving
+ * the prefab out has twice shipped as a silent gap.
*/
private documentOps(): {
/** The file this document is, or null when it is untitled. */
@@ -2293,9 +2261,7 @@ class ProjectStoreImpl {
ViewportController.frameSelection(content);
};
requestAnimationFrame(() => requestAnimationFrame(frameContent));
- // Seed the disk baseline from the file we just opened, so the first external
- // change to it is recognised as one — and a watcher event that carries no
- // actual change (a touch, a `.meta` write beside it) is not mistaken for one.
+ // Seed the baseline so the first external change to it reads as one.
this.diskText = await window.estella.fs.read(path).catch(() => null);
this.diskPath = path;
const returnLeaf = returnScene ? (returnScene.split('/').pop() ?? returnScene) : null;
@@ -2412,9 +2378,7 @@ class ProjectStoreImpl {
Toasts.push(t('proj.applyWriteFailed', { name: pe.path.split('/').pop() ?? pe.path }), 'error');
return;
}
- // Our own write is not an external change — record it, or the watcher fires
- // and offers to reload the file we just produced. `writeScene` does the same
- // for a scene; this is the prefab half of the same rule.
+ // Record our own write, or the watcher offers to reload what we just saved.
this.diskText = body;
this.diskPath = pe.path;
PrefabCache.put(pe.ref, prefab);
@@ -2456,9 +2420,8 @@ class ProjectStoreImpl {
}
}
- /** The file the editor currently has open as its document: the prefab in Prefab
- * Mode, else the scene. One accessor, so nothing has to remember that
- * `currentScene` is null while a prefab is open. */
+ /** The open document's file: the prefab in Prefab Mode, else the scene
+ * (`currentScene` is null while a prefab is open). */
private openDocumentPath(): string | null {
return this.documentOps().path();
}
@@ -2472,16 +2435,9 @@ class ProjectStoreImpl {
}
/**
- * Reconcile the open DOCUMENT with an on-disk change made outside the editor —
+ * Reconcile the open document with an on-disk change made outside the editor —
* seamless when clean, discard-guarded when there are unsaved edits. A change
* matching our own last write (or read) is a no-op.
- *
- * Both kinds, because both are edited in the same world and overwritten by the
- * same Save. This asked about the scene alone, and `currentScene` is null in
- * Prefab Mode — so a prefab changed on disk while open was invisible, and the
- * next Save wrote the stale tree over it without a word. Reloading a prefab is
- * re-entering Prefab Mode on it, which re-reads and re-flattens; the session
- * carries its own return scene and view forward, so the way out is unchanged.
*/
async reloadOpenDocumentFromDisk(): Promise<void> {
const target = this.openDocumentPath();
diff --git a/desktop/src/project/newAssetTypes.ts b/desktop/src/project/newAssetTypes.ts
index ce92d21d7..717338758 100644
--- a/desktop/src/project/newAssetTypes.ts
+++ b/desktop/src/project/newAssetTypes.ts
@@ -43,10 +43,8 @@ const shaderTemplateMenu = (make: (dir: string, templateId: string) => Promise<v
export const NEW_ASSET_TYPES: NewAssetEntry[] = [
{ labelKey: 'cb.menuNewScene', create: (dir) => ProjectStore.createSceneFile(dir), errorKey: 'cb.newSceneFailed' },
- // A blank-file creator, not an editor-backed one: entering Prefab Mode is a
- // document swap, which is guarded by unsaved changes and would put a prompt in
- // front of someone who asked for a file. So it lands in the browser and drops
- // into rename, like New Scene; double-click opens it.
+ // Blank-file, not editor-backed: opening Prefab Mode is a document swap, which
+ // prompts about unsaved changes — wrong for someone who asked for a file.
{ labelKey: 'cb.menuNewPrefab', create: (dir) => ProjectStore.createPrefabFile(dir), errorKey: 'cb.newPrefabFailed' },
// Returns void like the editor-backed creators: a script's editor is the one
// configured for source files, which the dialog hands it to itself — and its