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(editor): the question a component's fields provoke is asked at the component
yhha06b3c307451
diff --git a/desktop/src/engine/componentDocUrl.ts b/desktop/src/engine/componentDocUrl.tsnew file mode 100644index 000000000..43ee065a0--- /dev/null+++ b/desktop/src/engine/componentDocUrl.ts@@ -0,0 +1,23 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { COMPONENT_DOC_PATHS } from './componentDocs.generated';+import type { EditorLocale } from '@/i18n';++/** Where the published manual lives. The docs are not shipped inside the app. */+const DOCS_ROOT = 'https://estellaengine.com/docs';++/**+ * The manual page for a component, in the editor's own language — or null when+ * the engine has no such component (a project's own script-defined one, which+ * the manual cannot document).+ *+ * The path half is generated from the docs' curated table by+ * `tools/component-reference.mjs`, so the header link and the reference page can+ * never disagree about where a component is written up; `--check` fails when a+ * component gains or loses an entry.+ */+export function componentDocUrl(component: string, locale: EditorLocale): string | null {+ const path = COMPONENT_DOC_PATHS[component];+ if (!path) return null;+ return `${DOCS_ROOT}/${locale === 'zh-CN' ? 'zh-cn/' : ''}${path}`;+}diff --git a/desktop/src/engine/componentDocs.generated.ts b/desktop/src/engine/componentDocs.generated.tsnew file mode 100644index 000000000..998dfd684--- /dev/null+++ b/desktop/src/engine/componentDocs.generated.ts@@ -0,0 +1,84 @@+// Generated by tools/component-reference.mjs — do not edit. Run --update.+//+// Where the manual documents each component, so the Details panel header can+// link straight there: the question a component's fields provoke is asked while+// looking at them, not while browsing a sidebar.+export const COMPONENT_DOC_PATHS: Readonly<Record<string, string>> = {+ Animator: 'reference/components/animation/#animator',+ AudioListener: 'reference/components/gameplay/#audiolistener',+ AudioSource: 'reference/components/gameplay/#audiosource',+ BehaviorTreeAgent: 'reference/components/gameplay/#behaviortreeagent',+ BitmapText: 'reference/components/graphics/#bitmaptext',+ BoxCollider: 'reference/components/physics/#boxcollider',+ CacheAsBitmap: 'reference/components/graphics/#cacheasbitmap',+ Camera: 'reference/components/graphics/#camera',+ Canvas: 'reference/components/graphics/#canvas',+ CapsuleCollider: 'reference/components/physics/#capsulecollider',+ ChainCollider: 'reference/components/physics/#chaincollider',+ CharacterController: 'reference/components/physics/#charactercontroller',+ Children: 'reference/components/core/#children',+ CircleCollider: 'reference/components/physics/#circlecollider',+ Disabled: 'reference/components/core/#disabled',+ DistanceJoint: 'reference/components/physics/#distancejoint',+ DragState: 'reference/components/ui/#dragstate',+ Draggable: 'reference/components/ui/#draggable',+ DragonBonesAnimation: 'reference/components/animation/#dragonbonesanimation',+ EventBinding: 'reference/components/gameplay/#eventbinding',+ FlexContainer: 'reference/components/ui/#flexcontainer',+ Focusable: 'reference/components/ui/#focusable',+ FollowTarget: 'reference/components/graphics/#followtarget',+ Interactable: 'reference/components/ui/#interactable',+ Light2D: 'reference/components/graphics/#light2d',+ Marker: 'reference/components/world/#marker',+ Mesh2D: 'reference/components/graphics/#mesh2d',+ MotorJoint: 'reference/components/physics/#motorjoint',+ Name: 'reference/components/core/#name',+ NavAgent: 'reference/components/gameplay/#navagent',+ NetGhost: 'reference/components/gameplay/#netghost',+ OneWayPlatform: 'reference/components/physics/#onewayplatform',+ Parent: 'reference/components/core/#parent',+ ParticleEmitter: 'reference/components/world/#particleemitter',+ ParticleForceField: 'reference/components/world/#particleforcefield',+ Perceiver: 'reference/components/gameplay/#perceiver',+ Perception: 'reference/components/gameplay/#perception',+ PerceptionTarget: 'reference/components/gameplay/#perceptiontarget',+ PolygonCollider: 'reference/components/physics/#polygoncollider',+ PostProcessVolume: 'reference/components/graphics/#postprocessvolume',+ PrismaticJoint: 'reference/components/physics/#prismaticjoint',+ Replicated: 'reference/components/gameplay/#replicated',+ RevoluteJoint: 'reference/components/physics/#revolutejoint',+ RigidBody: 'reference/components/physics/#rigidbody',+ RuntimeOnly: 'reference/components/core/#runtimeonly',+ SafeArea: 'reference/components/ui/#safearea',+ SceneOwner: 'reference/components/core/#sceneowner',+ SegmentCollider: 'reference/components/physics/#segmentcollider',+ ShadowCaster2D: 'reference/components/graphics/#shadowcaster2d',+ ShapeRenderer: 'reference/components/graphics/#shaperenderer',+ SpineAnimation: 'reference/components/animation/#spineanimation',+ Sprite: 'reference/components/graphics/#sprite',+ SpriteAnimator: 'reference/components/animation/#spriteanimator',+ StateMachineAgent: 'reference/components/gameplay/#statemachineagent',+ Text: 'reference/components/ui/#text',+ TextInput: 'reference/components/ui/#textinput',+ ThemeStyle: 'reference/components/ui/#themestyle',+ Tilemap: 'reference/components/world/#tilemap',+ TilemapLayer: 'reference/components/world/#tilemaplayer',+ TimelinePlayer: 'reference/components/animation/#timelineplayer',+ TrailRenderer: 'reference/components/graphics/#trailrenderer',+ Transform: 'reference/components/core/#transform',+ UIController: 'reference/components/ui/#uicontroller',+ UIDialog: 'reference/components/ui/#uidialog',+ UIDropdown: 'reference/components/ui/#uidropdown',+ UIGear: 'reference/components/ui/#uigear',+ UIInteraction: 'reference/components/ui/#uiinteraction',+ UIMask: 'reference/components/ui/#uimask',+ UINode: 'reference/components/ui/#uinode',+ UIScroll: 'reference/components/ui/#uiscroll',+ UISlider: 'reference/components/ui/#uislider',+ UIToggle: 'reference/components/ui/#uitoggle',+ UIVisual: 'reference/components/ui/#uivisual',+ Velocity: 'reference/components/core/#velocity',+ Video: 'reference/components/graphics/#video',+ WeldJoint: 'reference/components/physics/#weldjoint',+ WheelJoint: 'reference/components/physics/#wheeljoint',+};diff --git a/desktop/src/i18n/messages/details.ts b/desktop/src/i18n/messages/details.tsindex fa4dc5014..1fd3f025e 100644--- a/desktop/src/i18n/messages/details.ts+++ b/desktop/src/i18n/messages/details.ts@@ -128,6 +128,7 @@ export const detailsMessages = defineMessages({'det.enableComponent': { en: 'Enable component', zh: '启用组件' },'det.disableComponent': { en: 'Disable component', zh: '禁用组件' },'det.componentOptions': { en: 'Component options', zh: '组件选项' },+ 'det.componentDocs': { en: 'What this component does', zh: '这个组件是做什么的' },'det.advanced': { en: 'Advanced', zh: '高级' },// — Entity kind pill (mirrors the Outliner's kind labels) —diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsxindex 21380fbd2..45b85d0b2 100644--- a/desktop/src/panels/Details.tsx+++ b/desktop/src/panels/Details.tsx@@ -23,6 +23,7 @@ import {MousePointerClick,Filter,Hexagon,+ HelpCircle,FolderOpen,Globe,Monitor,@@ -89,7 +90,8 @@ import { findAssetUsages } from '@/project/assetUsages';import { FindUsagesDialog } from '@/components/FindUsagesDialog';import { ProjectStore } from '@/project/ProjectStore';import { confirmDiscard, confirmDiscardDoc } from '@/project/discardGuard';-import { t } from '@/i18n';+import { t, editorLocale } from '@/i18n';+import { componentDocUrl } from '@/engine/componentDocUrl';import { MaterialDocument } from '@/material/MaterialDocument';import { DirtyRegistry } from '@/document/DirtyRegistry';import {@@ -2418,6 +2420,7 @@ function ComponentSection({hideFields?: ReadonlySet<string>;}) {const Icon = componentIcon(comp.name);+ const docUrl = componentDocUrl(comp.name, editorLocale);const overridden = comp.fields.some(isModified);// Categories default open, the Advanced fold defaults closed.const [openFolds, setOpenFolds] = useState<Record<string, boolean>>({});@@ -2488,6 +2491,20 @@ function ComponentSection({<Icon size={13} strokeWidth={1.9} /></span><span className="comp-name">{comp.label}</span>+ {docUrl && (+ // A real link, not an IPC call: the window's open handler already+ // routes any http target to the browser and denies in-app navigation.+ <a+ className="comp-help"+ href={docUrl}+ target="_blank"+ rel="noreferrer"+ title={t('det.componentDocs')}+ onClick={(e) => e.stopPropagation()}+ >+ <HelpCircle size={13} strokeWidth={2} />+ </a>+ )}{onMore && (<buttontype="button"diff --git a/desktop/src/theme/inspector.css b/desktop/src/theme/inspector.cssindex fd39f1b24..ff9d969fe 100644--- a/desktop/src/theme/inspector.css+++ b/desktop/src/theme/inspector.css@@ -74,9 +74,9 @@.comp.disabled .comp-icon, .comp.disabled .comp-name { opacity: .45; }.comp.disabled .comp-body { opacity: .5; }.comp-badge { font-size: var(--fs-2xs); color: var(--text-mute); font-family: var(--mono); }-.comp-menu { width: 22px; height: 22px; display: grid; place-items: center; color: var(--text-mute); border-radius: var(--r-sm); opacity: 0; transition: opacity var(--t-fast), color var(--t-fast), background var(--t-fast); }-.comp-head:hover .comp-menu { opacity: 1; }-.comp-menu:hover { color: var(--text); background: var(--srf-5); }+.comp-menu, .comp-help { width: 22px; height: 22px; display: grid; place-items: center; color: var(--text-mute); border-radius: var(--r-sm); opacity: 0; transition: opacity var(--t-fast), color var(--t-fast), background var(--t-fast); }+.comp-head:hover .comp-menu, .comp-head:hover .comp-help { opacity: 1; }+.comp-menu:hover, .comp-help:hover { color: var(--text); background: var(--srf-5); }.comp-body { display: grid; grid-template-rows: 0fr; transition: grid-template-rows var(--t-slow) var(--e-out); }.comp.open .comp-body { grid-template-rows: 1fr; }.comp-body > .cinner { overflow: hidden; }diff --git a/tools/component-reference.mjs b/tools/component-reference.mjsindex 15d59859e..a34fa3d3b 100644--- a/tools/component-reference.mjs+++ b/tools/component-reference.mjs@@ -39,6 +39,9 @@ const SDK_SRC = join(ROOT, 'sdk', 'src');const SDK_DIST = join(ROOT, 'sdk', 'dist', 'index.node.js');const SNAPSHOT = join(ROOT, 'docs', 'astro', 'src', 'data', 'components.generated.json');const CURATED = join(ROOT, 'docs', 'astro', 'src', 'data', 'componentDocs.ts');+// The editor's Details panel links each component header at its reference entry;+// the address is derived here so the two can never point at different pages.+const EDITOR_LINKS = join(ROOT, 'desktop', 'src', 'engine', 'componentDocs.generated.ts');const mode = process.argv[2];if (mode !== '--check' && mode !== '--update') {@@ -218,6 +221,38 @@ function curatedNames() {return [...src.matchAll(/^ {2}([A-Za-z0-9_]+): \{/gm)].map((m) => m[1]).sort();}+/** name -> category, read from the same curated table. */+function curatedCategories() {+ const src = readFileSync(CURATED, 'utf8');+ const out = {};+ for (const m of src.matchAll(/^ {2}([A-Za-z0-9_]+): \{ category: '([a-z]+)'/gm)) out[m[1]] = m[2];+ return out;+}++/** The editor's link table: component -> path under the docs root. */+function editorLinksSource(names) {+ const cats = curatedCategories();+ const rows = names+ .map((n) => ` ${/^[A-Za-z_][A-Za-z0-9_]*$/.test(n) ? n : `'${n}'`}: 'reference/components/${cats[n]}/#${n.toLowerCase()}',`)+ .join('\n');+ return `// Generated by tools/component-reference.mjs — do not edit. Run --update.+//+// Where the manual documents each component, so the Details panel header can+// link straight there: the question a component's fields provoke is asked while+// looking at them, not while browsing a sidebar.+export const COMPONENT_DOC_PATHS: Readonly<Record<string, string>> = {+${rows}+};+`;+}++/** Component names the editor link table carries. */+function editorLinkNames() {+ if (!existsSync(EDITOR_LINKS)) return null;+ const src = readFileSync(EDITOR_LINKS, 'utf8');+ return [...src.matchAll(/^ {2}'?([A-Za-z0-9_]+)'?: '/gm)].map((m) => m[1]).sort();+}+// ── run ──────────────────────────────────────────────────────────────────────const diff = (a, b) => ({ missing: b.filter((x) => !a.includes(x)), extra: a.filter((x) => !b.includes(x)) });@@ -227,11 +262,18 @@ if (mode === '--update') {writeFileSync(SNAPSHOT, `${JSON.stringify(snap, null, 2)}\n`);const fields = snap.components.reduce((n, c) => n + c.fields.length, 0);console.log(`component-reference: wrote ${snap.components.length} components, ${fields} fields`);+ const names = snap.components.map((c) => c.name);const curated = curatedNames();if (curated) {- const d = diff(curated, snap.components.map((c) => c.name));+ const d = diff(curated, names);if (d.missing.length) console.log(` still to describe in componentDocs.ts: ${d.missing.join(', ')}`);if (d.extra.length) console.log(` componentDocs.ts names components that no longer exist: ${d.extra.join(', ')}`);+ if (!d.missing.length && !d.extra.length) {+ writeFileSync(EDITOR_LINKS, editorLinksSource(names));+ console.log(` wrote the editor's link table (${names.length} entries)`);+ } else {+ console.log(" editor link table NOT written — describe the components above first");+ }}process.exit(0);}@@ -258,6 +300,14 @@ else {for (const n of dCur.extra) problems.push(`componentDocs.ts describes "${n}", which is not a component`);}+const links = editorLinkNames();+if (links === null) problems.push(`missing the editor's link table ${EDITOR_LINKS}`);+else {+ const dLink = diff(links, snapNames);+ for (const n of dLink.missing) problems.push(`the editor's Details panel has no doc link for "${n}"`);+ for (const n of dLink.extra) problems.push(`the editor links docs for "${n}", which is not a component`);+}+// The strongest check, where a built SDK makes it possible.let deep = 'names only (no built SDK)';if (existsSync(SDK_DIST)) {