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
docs(comments): cut the narrative back to the convention
yhhe7407a753094
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<vexport 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