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(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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.tsx
index 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 && (
<button
type="button"
diff --git a/desktop/src/theme/inspector.css b/desktop/src/theme/inspector.css
index 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.mjs
index 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)) {