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: a component reference, derived from the registry the inspector reads

yhh71e828f7d439
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index bf1bcab76..a12fd8886 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -275,6 +275,23 @@ export default defineConfig({
translations: { 'zh-CN': '参考' },
collapsed: true,
items: [
+ {
+ // Look-up by component name — the question the Details panel
+ // provokes ("what does this field do?"), which the task-shaped
+ // guides answer only if you already know which guide to open.
+ label: 'Component Reference',
+ translations: { 'zh-CN': '组件参考' },
+ collapsed: true,
+ items: [
+ { label: 'Core', translations: { 'zh-CN': '核心' }, slug: 'reference/components/core' },
+ { label: 'Graphics', translations: { 'zh-CN': '图形' }, slug: 'reference/components/graphics' },
+ { label: 'UI', translations: { 'zh-CN': 'UI' }, slug: 'reference/components/ui' },
+ { label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'reference/components/physics' },
+ { label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'reference/components/animation' },
+ { label: 'World', translations: { 'zh-CN': '世界' }, slug: 'reference/components/world' },
+ { label: 'Gameplay', translations: { 'zh-CN': '玩法' }, slug: 'reference/components/gameplay' },
+ ],
+ },
typeDocSidebarGroup,
// Doxygen output is merged in beside the Astro build, not routed by
// it, and it isn't translated. A root-relative link would get BOTH
diff --git a/docs/astro/scripts/verify-doc-links.mjs b/docs/astro/scripts/verify-doc-links.mjs
index 9fdb1833b..c51c03506 100644
--- a/docs/astro/scripts/verify-doc-links.mjs
+++ b/docs/astro/scripts/verify-doc-links.mjs
@@ -33,16 +33,31 @@ function htmlFiles(dir) {
return out;
}
-/** Does this in-site path resolve to something the build emitted? */
-function resolves(urlPath) {
+/** The file a `/docs/...` path is served from, or null if nothing emits it. */
+function pageFile(urlPath) {
const rel = urlPath.slice(BASE.length).replace(/^\/+/, '').replace(/\/+$/, '');
+ // The Doxygen C++ API is merged in by the site build script, not by Astro.
+ if (rel.startsWith('api/')) return 'external';
const asDir = join(DIST, ...rel.split('/'), 'index.html');
+ if (existsSync(asDir)) return asDir;
const asFile = join(DIST, ...rel.split('/'));
- if (existsSync(asDir)) return true;
- if (existsSync(asFile) && statSync(asFile).isFile()) return true;
- // The Doxygen C++ API is merged in by the site build script, not by Astro.
- if (rel.startsWith('api/')) return true;
- return false;
+ if (existsSync(asFile) && statSync(asFile).isFile()) return asFile;
+ return null;
+}
+
+/** Heading ids a page offers, so `#anchor` links are checked too — a heading's
+ * slug is not guessable by hand ("Bodies & colliders" is `bodies--colliders`,
+ * with two hyphens), which makes hand-written anchors quietly wrong. */
+const idCache = new Map();
+function idsOf(file) {
+ let ids = idCache.get(file);
+ if (!ids) {
+ ids = new Set();
+ const html = readFileSync(file, 'utf8');
+ for (const m of html.matchAll(/\sid="([^"]+)"/g)) ids.add(m[1]);
+ idCache.set(file, ids);
+ }
+ return ids;
}
function main() {
@@ -58,12 +73,18 @@ function main() {
// every locale it gets mirrored into (hence a segment test, not a prefix).
if (relative(DIST, page).split(sep).includes('api-ts')) continue;
const html = readFileSync(page, 'utf8');
- for (const m of html.matchAll(/href="(\/docs\/[^"#?]*)/g)) {
- const target = m[1];
+ for (const m of html.matchAll(/href="(\/docs\/[^"?]*)"/g)) {
+ const [path, fragment] = m[1].split('#');
checked++;
- if (resolves(target)) continue;
- if (!dead.has(target)) dead.set(target, new Set());
- dead.get(target).add(relative(DIST, page).replaceAll(sep, '/'));
+ const file = pageFile(path);
+ let problem = null;
+ if (!file) problem = m[1];
+ else if (fragment && file !== 'external' && !idsOf(file).has(decodeURIComponent(fragment))) {
+ problem = `${path}#${fragment} (page exists, no such heading)`;
+ }
+ if (!problem) continue;
+ if (!dead.has(problem)) dead.set(problem, new Set());
+ dead.get(problem).add(relative(DIST, page).replaceAll(sep, '/'));
}
}
console.log(`checked ${checked} internal links across ${pages.length} pages`);
diff --git a/docs/astro/src/components/ComponentReference.astro b/docs/astro/src/components/ComponentReference.astro
new file mode 100644
index 000000000..60f1da836
--- /dev/null
+++ b/docs/astro/src/components/ComponentReference.astro
@@ -0,0 +1,133 @@
+---
+// One category of the component reference: every component the engine registers,
+// its fields, types and authoring defaults. The field data is derived from the
+// engine's own registry (tools/component-reference.mjs), so it cannot drift from
+// the code; the summary and the link to the guide come from the curated table.
+import { COMPONENT_DOCS, CATEGORY_LABELS, type ComponentCategory } from '../data/componentDocs';
+import snapshot from '../data/components.generated.json';
+
+interface Props {
+ category: ComponentCategory;
+}
+const { category } = Astro.props;
+
+interface Field {
+ key: string;
+ type: string;
+ default: string;
+ doc?: string;
+ range?: string;
+ values?: string[];
+ readonly?: boolean;
+ replicated?: boolean;
+ advanced?: boolean;
+}
+interface Entry {
+ name: string;
+ source: 'cpp' | 'ts';
+ tag?: boolean;
+ transient?: boolean;
+ fields: Field[];
+}
+
+const entries = (snapshot.components as Entry[])
+ .filter((c) => COMPONENT_DOCS[c.name]?.category === category)
+ .sort((a, b) => a.name.localeCompare(b.name));
+
+// Chinese pages fall back to the English reference, the same way the generated
+// TypeScript API does, so links out of it must stay in the reader's locale.
+const zh = Astro.url.pathname.includes('/zh-cn/');
+const guide = (doc: { doc: string | null; anchor?: string; anchorZh?: string }) => {
+ // A translated heading has a translated id, so the English anchor would land
+ // on the right page at the wrong place — no anchor at all beats that.
+ const anchor = zh ? doc.anchorZh : doc.anchor;
+ return `/docs/${zh ? 'zh-cn/' : ''}${doc.doc}/${anchor ? `#${anchor}` : ''}`;
+};
+const id = (name: string) => name.toLowerCase();
+---
+
+<nav class="cr-index" aria-label={`${CATEGORY_LABELS[category]} components`}>
+ {entries.map((c) => <a href={`#${id(c.name)}`}><code>{c.name}</code></a>)}
+</nav>
+
+{entries.map((c) => {
+ const doc = COMPONENT_DOCS[c.name];
+ return (
+ <section class="cr-comp">
+ <h2 id={id(c.name)}>
+ <code>{c.name}</code>
+ {c.transient && <span class="cr-flag" title="Runtime-only state — scene saves omit it">transient</span>}
+ </h2>
+ <p class="cr-summary">{doc.summary}</p>
+ <p class="cr-where">
+ {doc.doc
+ ? <>Explained in <a href={guide(doc)}>{doc.doc}</a>.</>
+ : <em>No guide section covers this one yet.</em>}
+ </p>
+ {c.fields.length === 0
+ ? <p class="cr-where"><em>A tag — it carries no fields.</em></p>
+ : (
+ <div class="cr-table">
+ <table>
+ <thead>
+ <tr><th>Field</th><th>Type</th><th>Default</th><th>Notes</th></tr>
+ </thead>
+ <tbody>
+ {c.fields.map((f) => (
+ <tr>
+ <td><code>{f.key}</code></td>
+ <td><code>{f.type}</code></td>
+ <td><code>{f.default}</code></td>
+ <td>
+ {f.doc}
+ {f.values && <> One of {f.values.map((v, i) => <>{i > 0 && ', '}<code>{v}</code></>)}.</>}
+ {f.range && <> Range {f.range}.</>}
+ {f.readonly && <> <strong>Read-only</strong> — the engine computes it.</>}
+ {f.replicated && <> Replicated.</>}
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ )}
+ </section>
+ );
+})}
+
+<style>
+ .cr-index {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.4rem 0.5rem;
+ margin-block: 1rem 2rem;
+ padding-bottom: 1.5rem;
+ border-bottom: 1px solid var(--sl-color-hairline);
+ }
+ .cr-index a {
+ text-decoration: none;
+ border: 1px solid var(--sl-color-hairline);
+ border-radius: 0.35rem;
+ padding: 0.1rem 0.45rem;
+ }
+ .cr-index a:hover { border-color: var(--sl-color-accent); }
+ .cr-index code { background: none; font-size: var(--sl-text-sm); }
+ .cr-comp { margin-block: 2.5rem; }
+ .cr-comp h2 { margin-block: 0 0.5rem; }
+ .cr-summary { margin-block: 0 0.5rem; }
+ .cr-where { color: var(--sl-color-gray-3); font-size: var(--sl-text-sm); margin-block: 0 0.75rem; }
+ .cr-flag {
+ font-size: var(--sl-text-xs);
+ color: var(--sl-color-gray-2);
+ border: 1px solid var(--sl-color-hairline);
+ border-radius: 0.35rem;
+ padding: 0.05rem 0.35rem;
+ margin-inline-start: 0.5rem;
+ vertical-align: middle;
+ }
+ /* Four columns of prose and code do not fit a phone; let the table scroll
+ inside its own box rather than the page scroll sideways. */
+ .cr-table { overflow-x: auto; }
+ .cr-table table { margin: 0; }
+ .cr-table td:nth-child(4) { min-width: 16rem; }
+</style>
diff --git a/docs/astro/src/content/docs/reference/components/animation.mdx b/docs/astro/src/content/docs/reference/components/animation.mdx
new file mode 100644
index 000000000..a76715e8b
--- /dev/null
+++ b/docs/astro/src/content/docs/reference/components/animation.mdx
@@ -0,0 +1,14 @@
+---
+title: Animation components
+description: "Flipbook clips, animator controllers, timelines and skeletal runtimes."
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../components/ComponentReference.astro';
+
+Every field below is derived from the engine's own component registry — the same
+one the editor's **Details** panel reads — so the types and defaults here are the
+values you get when you add the component, and they cannot drift from the code.
+The prose that explains *how to use* each one lives in the guides linked per entry.
+
+<ComponentReference category="animation" />
diff --git a/docs/astro/src/content/docs/reference/components/core.mdx b/docs/astro/src/content/docs/reference/components/core.mdx
new file mode 100644
index 000000000..d13df5f77
--- /dev/null
+++ b/docs/astro/src/content/docs/reference/components/core.mdx
@@ -0,0 +1,14 @@
+---
+title: Core components
+description: "Transforms, hierarchy, naming and the tags the engine itself reads."
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../components/ComponentReference.astro';
+
+Every field below is derived from the engine's own component registry — the same
+one the editor's **Details** panel reads — so the types and defaults here are the
+values you get when you add the component, and they cannot drift from the code.
+The prose that explains *how to use* each one lives in the guides linked per entry.
+
+<ComponentReference category="core" />
diff --git a/docs/astro/src/content/docs/reference/components/gameplay.mdx b/docs/astro/src/content/docs/reference/components/gameplay.mdx
new file mode 100644
index 000000000..d9ff913be
--- /dev/null
+++ b/docs/astro/src/content/docs/reference/components/gameplay.mdx
@@ -0,0 +1,14 @@
+---
+title: Gameplay components
+description: "AI agents, event wiring, audio emitters and network replication."
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../components/ComponentReference.astro';
+
+Every field below is derived from the engine's own component registry — the same
+one the editor's **Details** panel reads — so the types and defaults here are the
+values you get when you add the component, and they cannot drift from the code.
+The prose that explains *how to use* each one lives in the guides linked per entry.
+
+<ComponentReference category="gameplay" />
diff --git a/docs/astro/src/content/docs/reference/components/graphics.mdx b/docs/astro/src/content/docs/reference/components/graphics.mdx
new file mode 100644
index 000000000..c45a0bd56
--- /dev/null
+++ b/docs/astro/src/content/docs/reference/components/graphics.mdx
@@ -0,0 +1,14 @@
+---
+title: Graphics components
+description: "Everything that draws: sprites, shapes, meshes, cameras, lights and post-processing."
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../components/ComponentReference.astro';
+
+Every field below is derived from the engine's own component registry — the same
+one the editor's **Details** panel reads — so the types and defaults here are the
+values you get when you add the component, and they cannot drift from the code.
+The prose that explains *how to use* each one lives in the guides linked per entry.
+
+<ComponentReference category="graphics" />
diff --git a/docs/astro/src/content/docs/reference/components/physics.mdx b/docs/astro/src/content/docs/reference/components/physics.mdx
new file mode 100644
index 000000000..a7fb48b7e
--- /dev/null
+++ b/docs/astro/src/content/docs/reference/components/physics.mdx
@@ -0,0 +1,14 @@
+---
+title: Physics components
+description: "Bodies, collider shapes, the character controller and every joint."
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../components/ComponentReference.astro';
+
+Every field below is derived from the engine's own component registry — the same
+one the editor's **Details** panel reads — so the types and defaults here are the
+values you get when you add the component, and they cannot drift from the code.
+The prose that explains *how to use* each one lives in the guides linked per entry.
+
+<ComponentReference category="physics" />
diff --git a/docs/astro/src/content/docs/reference/components/ui.mdx b/docs/astro/src/content/docs/reference/components/ui.mdx
new file mode 100644
index 000000000..20ba4c88a
--- /dev/null
+++ b/docs/astro/src/content/docs/reference/components/ui.mdx
@@ -0,0 +1,14 @@
+---
+title: UI components
+description: "The UI box model, its visuals, and the widgets built on top of them."
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../components/ComponentReference.astro';
+
+Every field below is derived from the engine's own component registry — the same
+one the editor's **Details** panel reads — so the types and defaults here are the
+values you get when you add the component, and they cannot drift from the code.
+The prose that explains *how to use* each one lives in the guides linked per entry.
+
+<ComponentReference category="ui" />
diff --git a/docs/astro/src/content/docs/reference/components/world.mdx b/docs/astro/src/content/docs/reference/components/world.mdx
new file mode 100644
index 000000000..38051e03e
--- /dev/null
+++ b/docs/astro/src/content/docs/reference/components/world.mdx
@@ -0,0 +1,14 @@
+---
+title: World components
+description: "Tilemaps, particles and the markers you place in a scene."
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../components/ComponentReference.astro';
+
+Every field below is derived from the engine's own component registry — the same
+one the editor's **Details** panel reads — so the types and defaults here are the
+values you get when you add the component, and they cannot drift from the code.
+The prose that explains *how to use* each one lives in the guides linked per entry.
+
+<ComponentReference category="world" />
diff --git a/docs/astro/src/content/docs/zh-cn/reference/components/animation.mdx b/docs/astro/src/content/docs/zh-cn/reference/components/animation.mdx
new file mode 100644
index 000000000..074a3d58e
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/reference/components/animation.mdx
@@ -0,0 +1,13 @@
+---
+title: 动画组件
+description: "逐帧动画、动画状态机、时间轴与骨骼运行时。"
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../../components/ComponentReference.astro';
+
+下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 **Details** 面板读的那一份——
+所以这里的类型和默认值就是你添加组件时真正拿到的值,且不可能与代码脱节。讲*怎么用*的正文在
+每条目所链接的指南里。字段说明取自 C++ `ES_PROPERTY` 处的原文,因此为英文。
+
+<ComponentReference category="animation" />
diff --git a/docs/astro/src/content/docs/zh-cn/reference/components/core.mdx b/docs/astro/src/content/docs/zh-cn/reference/components/core.mdx
new file mode 100644
index 000000000..86ba42cb5
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/reference/components/core.mdx
@@ -0,0 +1,13 @@
+---
+title: 核心组件
+description: "变换、层级、命名,以及引擎自身读取的标签。"
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../../components/ComponentReference.astro';
+
+下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 **Details** 面板读的那一份——
+所以这里的类型和默认值就是你添加组件时真正拿到的值,且不可能与代码脱节。讲*怎么用*的正文在
+每条目所链接的指南里。字段说明取自 C++ `ES_PROPERTY` 处的原文,因此为英文。
+
+<ComponentReference category="core" />
diff --git a/docs/astro/src/content/docs/zh-cn/reference/components/gameplay.mdx b/docs/astro/src/content/docs/zh-cn/reference/components/gameplay.mdx
new file mode 100644
index 000000000..e31526463
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/reference/components/gameplay.mdx
@@ -0,0 +1,13 @@
+---
+title: 玩法组件
+description: "AI 代理、事件连线、音频发声体与网络复制。"
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../../components/ComponentReference.astro';
+
+下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 **Details** 面板读的那一份——
+所以这里的类型和默认值就是你添加组件时真正拿到的值,且不可能与代码脱节。讲*怎么用*的正文在
+每条目所链接的指南里。字段说明取自 C++ `ES_PROPERTY` 处的原文,因此为英文。
+
+<ComponentReference category="gameplay" />
diff --git a/docs/astro/src/content/docs/zh-cn/reference/components/graphics.mdx b/docs/astro/src/content/docs/zh-cn/reference/components/graphics.mdx
new file mode 100644
index 000000000..c22e09cac
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/reference/components/graphics.mdx
@@ -0,0 +1,13 @@
+---
+title: 图形组件
+description: "所有会绘制的东西:精灵、图形、网格、相机、光照与后处理。"
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../../components/ComponentReference.astro';
+
+下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 **Details** 面板读的那一份——
+所以这里的类型和默认值就是你添加组件时真正拿到的值,且不可能与代码脱节。讲*怎么用*的正文在
+每条目所链接的指南里。字段说明取自 C++ `ES_PROPERTY` 处的原文,因此为英文。
+
+<ComponentReference category="graphics" />
diff --git a/docs/astro/src/content/docs/zh-cn/reference/components/physics.mdx b/docs/astro/src/content/docs/zh-cn/reference/components/physics.mdx
new file mode 100644
index 000000000..12bc45c25
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/reference/components/physics.mdx
@@ -0,0 +1,13 @@
+---
+title: 物理组件
+description: "刚体、碰撞体形状、角色控制器与全部关节。"
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../../components/ComponentReference.astro';
+
+下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 **Details** 面板读的那一份——
+所以这里的类型和默认值就是你添加组件时真正拿到的值,且不可能与代码脱节。讲*怎么用*的正文在
+每条目所链接的指南里。字段说明取自 C++ `ES_PROPERTY` 处的原文,因此为英文。
+
+<ComponentReference category="physics" />
diff --git a/docs/astro/src/content/docs/zh-cn/reference/components/ui.mdx b/docs/astro/src/content/docs/zh-cn/reference/components/ui.mdx
new file mode 100644
index 000000000..71f8ecbe8
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/reference/components/ui.mdx
@@ -0,0 +1,13 @@
+---
+title: UI 组件
+description: "UI 盒模型、外观,以及在其之上构建的控件。"
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../../components/ComponentReference.astro';
+
+下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 **Details** 面板读的那一份——
+所以这里的类型和默认值就是你添加组件时真正拿到的值,且不可能与代码脱节。讲*怎么用*的正文在
+每条目所链接的指南里。字段说明取自 C++ `ES_PROPERTY` 处的原文,因此为英文。
+
+<ComponentReference category="ui" />
diff --git a/docs/astro/src/content/docs/zh-cn/reference/components/world.mdx b/docs/astro/src/content/docs/zh-cn/reference/components/world.mdx
new file mode 100644
index 000000000..01b27a794
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/reference/components/world.mdx
@@ -0,0 +1,13 @@
+---
+title: 世界组件
+description: "瓦片地图、粒子,以及你在场景里摆放的标记。"
+tableOfContents: false
+---
+
+import ComponentReference from '../../../../../components/ComponentReference.astro';
+
+下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 **Details** 面板读的那一份——
+所以这里的类型和默认值就是你添加组件时真正拿到的值,且不可能与代码脱节。讲*怎么用*的正文在
+每条目所链接的指南里。字段说明取自 C++ `ES_PROPERTY` 处的原文,因此为英文。
+
+<ComponentReference category="world" />
diff --git a/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx b/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx
index 646344667..6f232c7b3 100644
--- a/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx
+++ b/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx
@@ -12,7 +12,7 @@ import { Aside } from '@astrojs/starlight/components';
一个控制器驱动多个元素,而整套东西就是普通的 ECS 数据(两个组件 `UIController` 和
`UIGear`),会随 [预制体](/docs/zh-cn/world/prefabs/) 一起走、序列化进场景。它是
-[按钮](/docs/zh-cn/ui/widgets/#button) 那种"单控件状态"的共享化、多页化推广——
+[按钮](/docs/zh-cn/ui/widgets/#button-按钮) 那种"单控件状态"的共享化、多页化推广——
页签、单选组、按钮状态、面板显隐,统一用一套机制。
## 控制器
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
new file mode 100644
index 000000000..a64f5b353
--- /dev/null
+++ b/docs/astro/src/data/componentDocs.ts
@@ -0,0 +1,143 @@
+// The curated half of the component reference: what each component is for, and
+// which guide explains it. The exhaustive half — every field, its type and its
+// authoring default — is derived from the engine's own registry into
+// `components.generated.json` by `tools/component-reference.mjs`, so it cannot
+// drift from the code.
+//
+// Keep one entry per registered component: `--check` fails when the engine gains
+// or loses one. `doc: null` means nothing in the manual explains it yet — the
+// reference still lists it, and the check prints it as a documentation gap.
+//
+// The anchors are real heading ids read off the built pages, not guesses (a
+// heading slug is not hand-derivable: "Bodies & colliders" is `bodies--colliders`,
+// with two hyphens). `npm run verify:links` resolves every one of them after the
+// build, so a wrong anchor fails there.
+
+export type ComponentCategory =
+ | 'core'
+ | 'graphics'
+ | 'ui'
+ | 'physics'
+ | 'animation'
+ | 'world'
+ | 'gameplay';
+
+export interface ComponentDoc {
+ /** Which reference page lists it. */
+ category: ComponentCategory;
+ /** One line: what it is for. */
+ summary: string;
+ /** Slug of the guide that explains it, or null when none does yet. */
+ doc: string | null;
+ /** Heading id on that guide, when a section is dedicated to it. */
+ anchor?: string;
+ /**
+ * The same heading on the Chinese page, whose id is its Chinese text. Derived
+ * by position — the translations are structural mirrors — and then verified
+ * like every other link by `npm run verify:links`.
+ */
+ anchorZh?: string;
+}
+
+export const CATEGORY_LABELS: Record<ComponentCategory, string> = {
+ core: 'Core',
+ graphics: 'Graphics',
+ ui: 'UI',
+ physics: 'Physics',
+ animation: 'Animation',
+ world: 'World',
+ gameplay: 'Gameplay',
+};
+
+export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
+ // ── Core ───────────────────────────────────────────────────────────────────
+ Transform: { category: 'core', summary: 'Position, rotation and scale — plus the read-only world-space values the engine composes down the parent chain.', doc: 'core-concepts/transforms', anchor: 'the-transform-component', anchorZh: 'transform-组件' },
+ Parent: { category: 'core', summary: 'The entity this one hangs under. The engine keeps it and `Children` in step; set it through the hierarchy API.', doc: 'core-concepts/transforms', anchor: 'parenting--hierarchy', anchorZh: '父子层级' },
+ Children: { category: 'core', summary: "The entity's children, maintained by the engine alongside `Parent`. Its order is the order children draw in.", doc: 'core-concepts/transforms', anchor: 'parenting--hierarchy', anchorZh: '父子层级' },
+ Name: { category: 'core', summary: "The entity's display name — what the World Outliner shows and what name lookups resolve against.", doc: null },
+ Velocity: { category: 'core', summary: 'Constant linear and angular motion applied every frame, with no physics body involved.', doc: 'scripting/overview', anchor: 'constant-motion-the-velocity-component', anchorZh: '匀速运动velocity-组件' },
+ SceneOwner: { category: 'core', summary: 'Which additively-loaded scene owns the entity, and whether it survives that scene being unloaded.', doc: 'world/scenes', anchor: 'persistent-entities', anchorZh: '持久化实体' },
+ Disabled: { category: 'core', summary: 'Tag added by `setEntityActive(false)`: an entity counts as active exactly while it is absent.', doc: null },
+ RuntimeOnly: { category: 'core', summary: 'Tag for a world-only derived entity (the layers a `Tilemap` projects, runtime tile colliders). Scene saves skip it, because persisting one would duplicate it against the next derivation.', doc: null },
+
+ // ── Graphics ───────────────────────────────────────────────────────────────
+ Sprite: { category: 'graphics', summary: 'Draws a texture in the world — tint, size, pivot, sorting layer, flipping, tiling and parallax.', doc: 'graphics/sprites', anchor: 'sprite-fields', anchorZh: 'sprite-字段' },
+ BitmapText: { category: 'graphics', summary: 'Text drawn in world space from a bitmap font, sorted alongside sprites (UI text is `Text`).', doc: 'graphics/sprites', anchor: 'bitmap-text-in-the-world', anchorZh: '世界空间位图文字' },
+ ShapeRenderer: { category: 'graphics', summary: 'A filled or stroked primitive — rectangle, circle, capsule — with no texture asset.', doc: 'graphics/sprites', anchor: 'shapes-without-a-texture', anchorZh: '不带纹理的图元' },
+ TrailRenderer: { category: 'graphics', summary: 'A ribbon trailing the entity as it moves, tapering and fading over its lifetime.', doc: 'graphics/sprites', anchor: 'motion-trails', anchorZh: '拖尾' },
+ CacheAsBitmap: { category: 'graphics', summary: 'Renders an expensive subtree once into a texture and reuses it until marked dirty.', doc: 'graphics/sprites', anchor: 'cache-as-bitmap', anchorZh: '位图缓存cache-as-bitmap' },
+ Camera: { category: 'graphics', summary: 'A view onto the world — projection, zoom, viewport rect, clear flags and render priority.', doc: 'graphics/camera', anchor: 'the-camera-component', anchorZh: 'camera-组件' },
+ FollowTarget: { category: 'graphics', summary: 'Makes a camera chase an entity, with an offset, a dead zone and eased catch-up.', doc: 'graphics/camera', anchor: 'follow-a-target', anchorZh: '跟随目标' },
+ Canvas: { category: 'graphics', summary: 'The design resolution and scale mode a scene is authored against — one per scene root.', doc: 'core-concepts/screen', anchor: 'the-canvas-component', anchorZh: 'canvas-组件' },
+ Light2D: { category: 'graphics', summary: 'A 2D light — point, directional, spot or ambient — that lit renderers and Lit2D materials receive.', doc: 'graphics/lighting', anchor: 'light-types', anchorZh: '光源类型' },
+ ShadowCaster2D: { category: 'graphics', summary: 'Marks a renderer as an occluder, so 2D lights cast shadows from its silhouette.', doc: 'graphics/lighting', anchor: 'casting-shadows', anchorZh: '投射阴影' },
+ PostProcessVolume: { category: 'graphics', summary: 'A stack of full-screen effects (bloom, vignette, colour grading) applied after the scene is drawn.', doc: 'graphics/post-processing', anchor: 'using-a-postprocessvolume', anchorZh: '使用-postprocessvolume' },
+ Mesh2D: { category: 'graphics', summary: 'Arbitrary 2D geometry — your own vertices, indices and material — drawn like any other renderer.', doc: 'graphics/drawing', anchor: 'custom-meshes-mesh2d', anchorZh: '自定义网格mesh2d' },
+ Video: { category: 'graphics', summary: 'Plays a video stream onto a surface in the world or the UI.', doc: 'graphics/video', anchor: 'the-video-component', anchorZh: 'video-组件' },
+
+ // ── UI ─────────────────────────────────────────────────────────────────────
+ UINode: { category: 'ui', summary: 'The UI box: size, position, margins and padding in design pixels. Every UI entity has one.', doc: 'ui/layout', anchor: 'uinode--the-box', anchorZh: 'uinode盒子' },
+ UIVisual: { category: 'ui', summary: 'What a UI node actually paints — a colour, a texture, or a nine-sliced sprite.', doc: 'ui/overview', anchor: 'uivisual-and-uimask', anchorZh: 'uivisual-与-uimask' },
+ UIMask: { category: 'ui', summary: "Clips descendants to this node's rect, with an optional alpha cutoff.", doc: 'ui/lists', anchor: 'clipping--uimask', anchorZh: '裁剪--uimask' },
+ UIScroll: { category: 'ui', summary: 'Scrollable content inside a clipped viewport, with momentum and scrollbars.', doc: 'ui/overview', anchor: 'scrolling', anchorZh: '滚动' },
+ FlexContainer: { category: 'ui', summary: 'Lays children out along an axis — direction, justification, alignment, wrapping and gaps.', doc: 'ui/layout', anchor: 'flexcontainer--laying-out-children', anchorZh: 'flexcontainer排布子项' },
+ Interactable: { category: 'ui', summary: 'Makes a UI node hit-testable, so pointer events can land on it.', doc: 'ui/interaction', anchor: 'hit-testing-interactable--uiinteraction', anchorZh: '命中测试interactable--uiinteraction' },
+ UIInteraction: { category: 'ui', summary: "Live pointer state for an interactable node — hovered, pressed, and the frame's transitions.", doc: 'ui/interaction', anchor: 'hit-testing-interactable--uiinteraction', anchorZh: '命中测试interactable--uiinteraction' },
+ Text: { category: 'ui', summary: 'UI text — font, size, alignment, colour, outline, shadow, rich-text markup and a localization key.', doc: 'ui/text', anchor: 'text-properties', anchorZh: 'text-属性' },
+ TextInput: { category: 'ui', summary: 'An editable text field with a caret, selection and IME support.', doc: 'ui/widgets', anchor: 'text-input', anchorZh: '文本输入' },
+ Draggable: { category: 'ui', summary: 'Lets the pointer drag a UI node, optionally constrained to an axis.', doc: 'ui/interaction', anchor: 'drag--drop', anchorZh: '拖放' },
+ DragState: { category: 'ui', summary: 'Transient per-frame geometry of a drag in progress; the drag system rebuilds it, scene saves omit it.', doc: 'ui/interaction', anchor: 'drag--drop', anchorZh: '拖放' },
+ Focusable: { category: 'ui', summary: 'Puts a widget in the keyboard focus order.', doc: 'ui/interaction', anchor: 'focus--keyboard', anchorZh: '焦点与键盘' },
+ SafeArea: { category: 'ui', summary: 'Insets an absolute UI node clear of notches and rounded corners.', doc: 'core-concepts/screen', anchor: 'safe-areas-notches--rounded-corners', anchorZh: '安全区刘海与圆角' },
+ ThemeStyle: { category: 'ui', summary: "Records which theme role an entity's colours came from, so a live theme swap can repaint it.", doc: 'ui/theming', anchor: 'how-widgets-consume-tokens', anchorZh: '控件如何消费令牌' },
+ UIController: { category: 'ui', summary: 'Shared named page state a whole subtree switches on — no bespoke per-widget state.', doc: 'ui/controllers', anchor: 'controllers', anchorZh: '控制器' },
+ UIGear: { category: 'ui', summary: 'Per-page field values a controller drives declaratively, authored from the Details panel.', doc: 'ui/controllers', anchor: 'gears', anchorZh: '属性绑定' },
+ UIDialog: { category: 'ui', summary: 'A modal dialog surface — backdrop, result, and open/close state.', doc: 'ui/widgets', anchor: 'dialog', anchorZh: 'dialog-对话框' },
+ UIDropdown: { category: 'ui', summary: 'A dropdown selector: its options and the selected index.', doc: 'ui/widgets', anchor: 'dropdown', anchorZh: 'dropdown-下拉框' },
+ UISlider: { category: 'ui', summary: 'A draggable value along a range, with an optional step.', doc: 'ui/widgets', anchor: 'slider', anchorZh: 'slider-滑块' },
+ UIToggle: { category: 'ui', summary: 'A two-state widget — checkbox or switch — and its group membership.', doc: 'ui/widgets', anchor: 'toggle', anchorZh: 'toggle-开关' },
+
+ // ── Physics ────────────────────────────────────────────────────────────────
+ RigidBody: { category: 'physics', summary: 'Puts the entity under the solver: static, kinematic or dynamic, with damping, gravity scale and sleep.', doc: 'gameplay/physics', anchor: 'rigidbody', anchorZh: 'rigidbody' },
+ BoxCollider: { category: 'physics', summary: 'A rectangular collision shape. Sizes are in **metres**, not pixels.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
+ CircleCollider: { category: 'physics', summary: 'A circular collision shape. Radius is in **metres**.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
+ CapsuleCollider: { category: 'physics', summary: 'A capsule collision shape — the usual choice for a character body.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
+ SegmentCollider: { category: 'physics', summary: 'A single line segment — a one-sided wall or edge.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
+ PolygonCollider: { category: 'physics', summary: 'A convex polygon collision shape from your own points.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
+ ChainCollider: { category: 'physics', summary: 'A polyline of edges — open or looped — for static terrain.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
+ CharacterController: { category: 'physics', summary: 'Kinematic character movement that slides along walls, climbs slopes and reports ground contact.', doc: 'gameplay/physics', anchor: 'character-controller', anchorZh: '角色控制器' },
+ OneWayPlatform: { category: 'physics', summary: 'Makes a collider solid from one side only, so a body passes up through it and lands on top.', doc: 'gameplay/physics', anchor: 'one-way-platforms', anchorZh: '单向平台' },
+ DistanceJoint: { category: 'physics', summary: 'Holds two bodies a fixed (or spring-limited) distance apart.', doc: 'gameplay/physics', anchor: 'joints', anchorZh: '关节' },
+ RevoluteJoint: { category: 'physics', summary: 'Pins two bodies at a point and lets them rotate — a hinge, with optional limits and a motor.', doc: 'gameplay/physics', anchor: 'joints', anchorZh: '关节' },
+ PrismaticJoint: { category: 'physics', summary: 'Constrains two bodies to slide along one axis — a piston or lift.', doc: 'gameplay/physics', anchor: 'joints', anchorZh: '关节' },
+ WeldJoint: { category: 'physics', summary: 'Locks two bodies rigidly together, with optional spring give.', doc: 'gameplay/physics', anchor: 'joints', anchorZh: '关节' },
+ MotorJoint: { category: 'physics', summary: 'Drives one body toward a target offset and angle — moving platforms and conveyors.', doc: 'gameplay/physics', anchor: 'joints', anchorZh: '关节' },
+ WheelJoint: { category: 'physics', summary: 'A suspension axis plus a spinning axle — the wheel half of a vehicle.', doc: 'gameplay/physics', anchor: 'joints', anchorZh: '关节' },
+
+ // ── Animation ──────────────────────────────────────────────────────────────
+ Animator: { category: 'animation', summary: 'Runs an animator controller — states, transitions and blend trees — over the entity.', doc: 'animation/overview', anchor: 'animator-state-machine', anchorZh: '动画状态机' },
+ SpriteAnimator: { category: 'animation', summary: 'Plays a flipbook clip by swapping the sprite frame, with speed, looping and frame events.', doc: 'animation/overview', anchor: 'sprite-animation', anchorZh: '精灵动画' },
+ TimelinePlayer: { category: 'animation', summary: 'Plays a timeline asset — keyframed tracks across many entities — with wrap modes and playback control.', doc: 'animation/timeline', anchor: 'attach-a-timeline', anchorZh: '附加时间轴' },
+ SpineAnimation: { category: 'animation', summary: 'A Spine skeleton: its skeleton and atlas assets, current animation, skin and mix settings.', doc: 'animation/spine', anchor: 'the-spineanimation-component', anchorZh: 'spineanimation-组件' },
+ DragonBonesAnimation: { category: 'animation', summary: 'A DragonBones armature: its skeleton and atlas assets, armature choice and playback state.', doc: 'animation/dragonbones', anchor: 'the-dragonbonesanimation-component', anchorZh: 'dragonbonesanimation-组件' },
+
+ // ── World ──────────────────────────────────────────────────────────────────
+ Tilemap: { category: 'world', summary: 'A Tiled map asset projected into the scene; the engine derives one layer entity per map layer.', doc: 'world/tilemaps', anchor: 'load-a-tiled-map', anchorZh: '加载-tiled-地图' },
+ TilemapLayer: { category: 'world', summary: 'One layer of tiles — its tileset, cell size, orientation, sorting and collision.', doc: 'world/tilemaps', anchor: 'the-tilemaplayer-component', anchorZh: 'tilemaplayer-组件' },
+ ParticleEmitter: { category: 'world', summary: 'A particle system: emission, lifetime, shape, forces, noise, colour and size over life, sub-emitters and trails.', doc: 'world/particles', anchor: 'particleemitter-reference', anchorZh: 'particleemitter-字段参考' },
+ ParticleForceField: { category: 'world', summary: 'A field that pushes particles around — point, directional, vortex or drag.', doc: 'world/particles', anchor: 'force-fields', anchorZh: '力场' },
+ Marker: { category: 'world', summary: 'A named point or region of gameplay interest — spawn point, waypoint, trigger zone — queryable like any component.', doc: 'gameplay/markers', anchor: 'marker-component-reference', anchorZh: 'marker-组件参考' },
+
+ // ── Gameplay ───────────────────────────────────────────────────────────────
+ NavAgent: { category: 'gameplay', summary: 'Steers an entity along a path found on the navigation grid.', doc: 'gameplay/ai', anchor: 'moving-an-agent', anchorZh: '移动-agent' },
+ Perceiver: { category: 'gameplay', summary: 'Senses nearby perception targets within a sight cone and range.', doc: 'gameplay/ai', anchor: 'perception', anchorZh: '感知' },
+ Perception: { category: 'gameplay', summary: "What a perceiver currently sees — written each frame for the entity's own logic to read.", doc: 'gameplay/ai', anchor: 'perception', anchorZh: '感知' },
+ PerceptionTarget: { category: 'gameplay', summary: 'Tag: perceivers can see this entity.', doc: 'gameplay/ai', anchor: 'perception', anchorZh: '感知' },
+ StateMachineAgent: { category: 'gameplay', summary: 'Runs a gameplay state machine asset, calling registry actions as states enter, update and exit.', doc: 'gameplay/ai', anchor: 'state-machines', anchorZh: '状态机' },
+ BehaviorTreeAgent: { category: 'gameplay', summary: 'Ticks a behavior tree asset against a blackboard, calling registry actions at its leaves.', doc: 'gameplay/ai', anchor: 'behavior-trees', anchorZh: '行为树' },
+ EventBinding: { category: 'gameplay', summary: 'Wires an event on this entity to named actions — gameplay authored in the inspector, with no script.', doc: 'scripting/events', anchor: 'the-data', anchorZh: '数据本身' },
+ AudioSource: { category: 'gameplay', summary: 'Declarative playback attached to an entity, attenuated by distance when spatial.', doc: 'assets/audio', anchor: 'declarative-playback--audiosource', anchorZh: '声明式播放--audiosource' },
+ AudioListener: { category: 'gameplay', summary: 'The ear spatial audio is mixed relative to — usually the camera or the player.', doc: 'assets/audio', anchor: 'spatial-audio', anchorZh: '空间音频' },
+ Replicated: { category: 'gameplay', summary: 'Marks an entity the server replicates to every client.', doc: 'scripting/networking', anchor: 'state-replication--multiplayer-entities', anchorZh: '状态复制多人实体同步' },
+ NetGhost: { category: 'gameplay', summary: 'Tag: this entity is a client-side proxy of one the server owns.', doc: 'scripting/networking', anchor: 'state-replication--multiplayer-entities', anchorZh: '状态复制多人实体同步' },
+};
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
new file mode 100644
index 000000000..a66f2c320
--- /dev/null
+++ b/docs/astro/src/data/components.generated.json
@@ -0,0 +1,4088 @@
+{
+ "generatedBy": "tools/component-reference.mjs",
+ "abiLayoutHash": null,
+ "components": [
+ {
+ "name": "Animator",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "controller",
+ "type": "Asset<animatorcontroller>",
+ "default": "none"
+ },
+ {
+ "key": "currentState",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "AudioListener",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "AudioSource",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "clip",
+ "type": "Asset<audio>",
+ "default": "none"
+ },
+ {
+ "key": "bus",
+ "type": "string",
+ "default": "\"sfx\""
+ },
+ {
+ "key": "volume",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "pitch",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "loop",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "playOnAwake",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "spatial",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "minDistance",
+ "type": "number",
+ "default": "100"
+ },
+ {
+ "key": "maxDistance",
+ "type": "number",
+ "default": "1000"
+ },
+ {
+ "key": "attenuationModel",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "rolloff",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "priority",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "volume",
+ "pitch",
+ "minDistance",
+ "maxDistance",
+ "attenuationModel",
+ "rolloff",
+ "priority"
+ ]
+ },
+ {
+ "name": "BehaviorTreeAgent",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "bt",
+ "type": "Asset<behaviortree>",
+ "default": "none"
+ },
+ {
+ "key": "status",
+ "type": "string",
+ "default": "empty",
+ "doc": "Last root status (runtime, read-only).",
+ "advanced": true
+ }
+ ]
+ },
+ {
+ "name": "BitmapText",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "text",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "fontSize",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 1"
+ },
+ {
+ "key": "align",
+ "type": "enum",
+ "default": "Left",
+ "values": [
+ "Left",
+ "Center",
+ "Right"
+ ]
+ },
+ {
+ "key": "spacing",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "parallax",
+ "type": "Vec2",
+ "default": "(1, 1)",
+ "doc": "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).",
+ "advanced": true
+ },
+ {
+ "key": "layer",
+ "type": "number",
+ "default": "0",
+ "range": "step 1"
+ },
+ {
+ "key": "font",
+ "type": "Asset<font>",
+ "default": "none"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "color.r",
+ "color.g",
+ "color.b",
+ "color.a"
+ ]
+ },
+ {
+ "name": "BoxCollider",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "halfExtents",
+ "type": "Vec2",
+ "default": "(0.5, 0.5)"
+ },
+ {
+ "key": "offset",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "radius",
+ "type": "number",
+ "default": "0.05"
+ },
+ {
+ "key": "density",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "friction",
+ "type": "number",
+ "default": "0.3"
+ },
+ {
+ "key": "restitution",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "isSensor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "categoryBits",
+ "type": "number",
+ "default": "1",
+ "advanced": true
+ },
+ {
+ "key": "maskBits",
+ "type": "number",
+ "default": "65535",
+ "advanced": true
+ }
+ ]
+ },
+ {
+ "name": "CacheAsBitmap",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "dirty",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "width",
+ "type": "number",
+ "default": "256"
+ },
+ {
+ "key": "height",
+ "type": "number",
+ "default": "256"
+ }
+ ],
+ "animatable": [
+ "width",
+ "height"
+ ]
+ },
+ {
+ "name": "Camera",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "projectionType",
+ "type": "enum",
+ "default": "Orthographic",
+ "doc": "Orthographic (2D) or Perspective projection.",
+ "values": [
+ "Perspective",
+ "Orthographic"
+ ]
+ },
+ {
+ "key": "fov",
+ "type": "number",
+ "default": "60",
+ "range": "1–179"
+ },
+ {
+ "key": "orthoSize",
+ "type": "number",
+ "default": "540",
+ "doc": "Half the visible height in world units (Orthographic).",
+ "range": "≥ 0"
+ },
+ {
+ "key": "nearPlane",
+ "type": "number",
+ "default": "0.1",
+ "range": "≥ 0",
+ "advanced": true
+ },
+ {
+ "key": "farPlane",
+ "type": "number",
+ "default": "1000",
+ "range": "≥ 0",
+ "advanced": true
+ },
+ {
+ "key": "aspectRatio",
+ "type": "number",
+ "default": "1.77",
+ "advanced": true
+ },
+ {
+ "key": "isActive",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "priority",
+ "type": "number",
+ "default": "0",
+ "range": "step 1",
+ "advanced": true
+ },
+ {
+ "key": "viewport",
+ "type": "Vec4",
+ "default": "(0, 0, 1, 1)"
+ },
+ {
+ "key": "clearFlags",
+ "type": "number",
+ "default": "3",
+ "doc": "Which buffers to clear before rendering this camera."
+ },
+ {
+ "key": "pixelPerfect",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Snap the camera to the pixel grid for crisp pixel-art (Orthographic).",
+ "advanced": true
+ },
+ {
+ "key": "showFrustum",
+ "type": "boolean",
+ "default": "false",
+ "advanced": true
+ }
+ ],
+ "animatable": [
+ "orthoSize"
+ ]
+ },
+ {
+ "name": "Canvas",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "designResolution",
+ "type": "Vec2",
+ "default": "(1920, 1080)"
+ },
+ {
+ "key": "pixelsPerUnit",
+ "type": "number",
+ "default": "100",
+ "doc": "World pixels per physics meter (Box2D + tile collider scale).",
+ "range": "≥ 1"
+ },
+ {
+ "key": "scaleMode",
+ "type": "enum",
+ "default": "FixedHeight",
+ "doc": "How the canvas adapts the design resolution to the screen.",
+ "values": [
+ "FixedWidth",
+ "FixedHeight",
+ "Expand",
+ "Shrink",
+ "Match"
+ ]
+ },
+ {
+ "key": "matchWidthOrHeight",
+ "type": "number",
+ "default": "0.5",
+ "doc": "0 matches width, 1 matches height (Match mode only).",
+ "range": "0–1"
+ },
+ {
+ "key": "backgroundColor",
+ "type": "Color",
+ "default": "#000000"
+ }
+ ]
+ },
+ {
+ "name": "CapsuleCollider",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "radius",
+ "type": "number",
+ "default": "0.25"
+ },
+ {
+ "key": "halfHeight",
+ "type": "number",
+ "default": "0.5"
+ },
+ {
+ "key": "offset",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "density",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "friction",
+ "type": "number",
+ "default": "0.3"
+ },
+ {
+ "key": "restitution",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "isSensor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "categoryBits",
+ "type": "number",
+ "default": "1",
+ "advanced": true
+ },
+ {
+ "key": "maskBits",
+ "type": "number",
+ "default": "65535",
+ "advanced": true
+ }
+ ]
+ },
+ {
+ "name": "ChainCollider",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "points",
+ "type": "Vec2[]",
+ "default": "[{\"x\":-1,\"y\":0},{\"x\":0,\"y\":0.5},{\"x\":1,\"y\":0},{\"x\":0,\"y\":-0.5}]"
+ },
+ {
+ "key": "isLoop",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "friction",
+ "type": "number",
+ "default": "0.6"
+ },
+ {
+ "key": "restitution",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "categoryBits",
+ "type": "number",
+ "default": "1",
+ "advanced": true
+ },
+ {
+ "key": "maskBits",
+ "type": "number",
+ "default": "65535",
+ "advanced": true
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "friction",
+ "restitution",
+ "categoryBits",
+ "maskBits"
+ ]
+ },
+ {
+ "name": "CharacterController",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "velocity",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "up",
+ "type": "Vec2",
+ "default": "(0, 1)",
+ "advanced": true
+ },
+ {
+ "key": "floorMaxAngle",
+ "type": "number",
+ "default": "0.7854",
+ "doc": "Max walkable slope from up (radians)",
+ "range": "0–1.5708, step 0.01"
+ },
+ {
+ "key": "maxSlides",
+ "type": "number",
+ "default": "4",
+ "range": "1–8, step 1",
+ "advanced": true
+ },
+ {
+ "key": "skinWidth",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 0, step 0.25",
+ "advanced": true
+ },
+ {
+ "key": "snapLength",
+ "type": "number",
+ "default": "0",
+ "doc": "Floor-snap probe length; 0 disables stair/slope stick",
+ "range": "≥ 0, step 0.5"
+ },
+ {
+ "key": "slideOnCeiling",
+ "type": "boolean",
+ "default": "true",
+ "advanced": true
+ },
+ {
+ "key": "maskBits",
+ "type": "number",
+ "default": "65535",
+ "advanced": true
+ },
+ {
+ "key": "isOnFloor",
+ "type": "boolean",
+ "default": "false",
+ "advanced": true
+ },
+ {
+ "key": "isOnWall",
+ "type": "boolean",
+ "default": "false",
+ "advanced": true
+ },
+ {
+ "key": "isOnCeiling",
+ "type": "boolean",
+ "default": "false",
+ "advanced": true
+ },
+ {
+ "key": "floorNormal",
+ "type": "Vec2",
+ "default": "(0, 0)",
+ "advanced": true
+ },
+ {
+ "key": "realVelocity",
+ "type": "Vec2",
+ "default": "(0, 0)",
+ "advanced": true
+ }
+ ],
+ "animatable": [
+ "velocity.x",
+ "velocity.y",
+ "up.x",
+ "up.y",
+ "floorMaxAngle",
+ "maxSlides",
+ "skinWidth",
+ "snapLength",
+ "maskBits",
+ "floorNormal.x",
+ "floorNormal.y",
+ "realVelocity.x",
+ "realVelocity.y"
+ ]
+ },
+ {
+ "name": "Children",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "entities",
+ "type": "Entity",
+ "default": ""
+ }
+ ]
+ },
+ {
+ "name": "CircleCollider",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "radius",
+ "type": "number",
+ "default": "0.5"
+ },
+ {
+ "key": "offset",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "density",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "friction",
+ "type": "number",
+ "default": "0.3"
+ },
+ {
+ "key": "restitution",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "isSensor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "categoryBits",
+ "type": "number",
+ "default": "1",
+ "advanced": true
+ },
+ {
+ "key": "maskBits",
+ "type": "number",
+ "default": "65535",
+ "advanced": true
+ }
+ ]
+ },
+ {
+ "name": "Disabled",
+ "source": "ts",
+ "fields": [],
+ "tag": true
+ },
+ {
+ "name": "DistanceJoint",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "connectedEntity",
+ "type": "Entity",
+ "default": "-1"
+ },
+ {
+ "key": "anchorA",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "anchorB",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "length",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "enableSpring",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "hertz",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "dampingRatio",
+ "type": "number",
+ "default": "0.5"
+ },
+ {
+ "key": "enableLimit",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "minLength",
+ "type": "number",
+ "default": "0.5"
+ },
+ {
+ "key": "maxLength",
+ "type": "number",
+ "default": "2"
+ },
+ {
+ "key": "enableMotor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "maxMotorForce",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "motorSpeed",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "collideConnected",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "connectedEntity",
+ "anchorA.x",
+ "anchorA.y",
+ "anchorB.x",
+ "anchorB.y",
+ "length",
+ "hertz",
+ "dampingRatio",
+ "minLength",
+ "maxLength",
+ "maxMotorForce",
+ "motorSpeed"
+ ]
+ },
+ {
+ "name": "DragState",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "isDragging",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "startWorldPos",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "currentWorldPos",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "deltaWorld",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "totalDeltaWorld",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "pointerStartWorld",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ }
+ ],
+ "transient": true,
+ "animatable": [
+ "startWorldPos.x",
+ "startWorldPos.y",
+ "currentWorldPos.x",
+ "currentWorldPos.y",
+ "deltaWorld.x",
+ "deltaWorld.y",
+ "totalDeltaWorld.x",
+ "totalDeltaWorld.y",
+ "pointerStartWorld.x",
+ "pointerStartWorld.y"
+ ]
+ },
+ {
+ "name": "Draggable",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "dragThreshold",
+ "type": "number",
+ "default": "5"
+ },
+ {
+ "key": "lockX",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "lockY",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "constraintMin",
+ "type": "unknown",
+ "default": "—"
+ },
+ {
+ "key": "constraintMax",
+ "type": "unknown",
+ "default": "—"
+ }
+ ],
+ "animatable": [
+ "dragThreshold"
+ ]
+ },
+ {
+ "name": "DragonBonesAnimation",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "skeletonPath",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "atlasPath",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "armature",
+ "type": "enum (dragonbonesArmatures)",
+ "default": "empty"
+ },
+ {
+ "key": "animation",
+ "type": "enum (dragonbonesAnimations)",
+ "default": "empty"
+ },
+ {
+ "key": "timeScale",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 0"
+ },
+ {
+ "key": "loop",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "playing",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "fadeInTime",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0, step 0.05"
+ },
+ {
+ "key": "flipX",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "flipY",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "layer",
+ "type": "enum (sortingLayers)",
+ "default": "0",
+ "range": "step 1"
+ },
+ {
+ "key": "skeletonScale",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 0"
+ },
+ {
+ "key": "material",
+ "type": "Asset<material>",
+ "default": "none"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "EventBinding",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "rows",
+ "type": "array",
+ "default": "empty"
+ }
+ ]
+ },
+ {
+ "name": "FlexContainer",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "direction",
+ "type": "enum",
+ "default": "Row",
+ "values": [
+ "Row",
+ "Column",
+ "RowReverse",
+ "ColumnReverse"
+ ]
+ },
+ {
+ "key": "wrap",
+ "type": "enum",
+ "default": "NoWrap",
+ "values": [
+ "NoWrap",
+ "Wrap"
+ ]
+ },
+ {
+ "key": "justifyContent",
+ "type": "enum",
+ "default": "Start",
+ "values": [
+ "Start",
+ "Center",
+ "End",
+ "SpaceBetween",
+ "SpaceAround",
+ "SpaceEvenly"
+ ]
+ },
+ {
+ "key": "alignItems",
+ "type": "enum",
+ "default": "Stretch",
+ "values": [
+ "Start",
+ "Center",
+ "End",
+ "Stretch"
+ ]
+ },
+ {
+ "key": "alignContent",
+ "type": "enum",
+ "default": "Start",
+ "values": [
+ "Start",
+ "Center",
+ "End",
+ "Stretch",
+ "SpaceBetween",
+ "SpaceAround"
+ ]
+ },
+ {
+ "key": "gap",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "padding",
+ "type": "Padding",
+ "default": "{\"left\":0,\"top\":0,\"right\":0,\"bottom\":0}"
+ }
+ ]
+ },
+ {
+ "name": "Focusable",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "tabIndex",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "isFocused",
+ "type": "boolean",
+ "default": "false"
+ }
+ ],
+ "animatable": [
+ "tabIndex"
+ ]
+ },
+ {
+ "name": "FollowTarget",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "target",
+ "type": "number",
+ "default": "-1"
+ },
+ {
+ "key": "offsetX",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "offsetY",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "deadzone",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "damping",
+ "type": "number",
+ "default": "0.25"
+ }
+ ],
+ "animatable": [
+ "target",
+ "offsetX",
+ "offsetY",
+ "deadzone",
+ "damping"
+ ]
+ },
+ {
+ "name": "Interactable",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "blockRaycast",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "raycastTarget",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "Light2D",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "type",
+ "type": "enum",
+ "default": "Point",
+ "doc": "Point, Directional, Ambient, or Spot.",
+ "values": [
+ "Point",
+ "Directional",
+ "Ambient",
+ "Spot"
+ ]
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "intensity",
+ "type": "number",
+ "default": "1",
+ "doc": "Brightness multiplier of the light.",
+ "range": "≥ 0"
+ },
+ {
+ "key": "radius",
+ "type": "number",
+ "default": "200",
+ "doc": "Falloff reach in world units (Point / Spot).",
+ "range": "≥ 0"
+ },
+ {
+ "key": "direction",
+ "type": "Vec2",
+ "default": "(0, 0)",
+ "doc": "Aim direction (Directional / Spot).",
+ "advanced": true
+ },
+ {
+ "key": "innerAngle",
+ "type": "number",
+ "default": "30",
+ "range": "0–180",
+ "advanced": true
+ },
+ {
+ "key": "outerAngle",
+ "type": "number",
+ "default": "45",
+ "range": "0–180",
+ "advanced": true
+ },
+ {
+ "key": "shadowSoftness",
+ "type": "number",
+ "default": "0",
+ "doc": "Shadow softness (light-source size); 0 = hard edge.",
+ "range": "≥ 0"
+ },
+ {
+ "key": "shadowDistance",
+ "type": "number",
+ "default": "0",
+ "doc": "Directional shadow distance; 0 = no directional shadow.",
+ "range": "≥ 0",
+ "advanced": true
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "color.r",
+ "color.g",
+ "color.b",
+ "color.a",
+ "intensity",
+ "radius",
+ "innerAngle",
+ "outerAngle",
+ "shadowSoftness",
+ "shadowDistance"
+ ]
+ },
+ {
+ "name": "Marker",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "type",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "properties",
+ "type": "object",
+ "default": "empty"
+ }
+ ]
+ },
+ {
+ "name": "Mesh2D",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "texture",
+ "type": "Asset<texture>",
+ "default": "none"
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff",
+ "doc": "Tint multiplied into the vertex colors (white = unchanged)."
+ },
+ {
+ "key": "layer",
+ "type": "enum (sortingLayers)",
+ "default": "0",
+ "doc": "Sorting layer — controls draw order across renderables.",
+ "range": "step 1"
+ },
+ {
+ "key": "lit",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Receive 2D lights: Light2D entities light this mesh (flat normal). A custom material overrides this."
+ },
+ {
+ "key": "parallax",
+ "type": "Vec2",
+ "default": "(1, 1)",
+ "doc": "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).",
+ "advanced": true
+ },
+ {
+ "key": "material",
+ "type": "Asset<material>",
+ "default": "none",
+ "advanced": true
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "geometry",
+ "type": "object",
+ "default": "{\"positions\":[],\"indices\":[]}"
+ }
+ ],
+ "animatable": [
+ "color.r",
+ "color.g",
+ "color.b",
+ "color.a"
+ ]
+ },
+ {
+ "name": "MotorJoint",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "connectedEntity",
+ "type": "Entity",
+ "default": "-1"
+ },
+ {
+ "key": "linearVelocity",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "maxVelocityForce",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "angularVelocity",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "maxVelocityTorque",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "linearHertz",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "linearDampingRatio",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "maxSpringForce",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "angularHertz",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "angularDampingRatio",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "maxSpringTorque",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "collideConnected",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "connectedEntity",
+ "linearVelocity.x",
+ "linearVelocity.y",
+ "maxVelocityForce",
+ "angularVelocity",
+ "maxVelocityTorque",
+ "linearHertz",
+ "linearDampingRatio",
+ "maxSpringForce",
+ "angularHertz",
+ "angularDampingRatio",
+ "maxSpringTorque"
+ ]
+ },
+ {
+ "name": "Name",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "value",
+ "type": "string",
+ "default": "empty"
+ }
+ ]
+ },
+ {
+ "name": "NavAgent",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "speed",
+ "type": "number",
+ "default": "120",
+ "range": "≥ 0"
+ },
+ {
+ "key": "radius",
+ "type": "number",
+ "default": "12",
+ "range": "≥ 1"
+ },
+ {
+ "key": "arriveRadius",
+ "type": "number",
+ "default": "6",
+ "range": "≥ 0"
+ },
+ {
+ "key": "repathInterval",
+ "type": "number",
+ "default": "0.5",
+ "doc": "Replan cadence while moving; 0 = only when the target changes.",
+ "range": "≥ 0"
+ },
+ {
+ "key": "hasTarget",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "targetX",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "targetY",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "arrived",
+ "type": "boolean",
+ "default": "false",
+ "advanced": true
+ }
+ ],
+ "animatable": [
+ "speed",
+ "radius",
+ "arriveRadius",
+ "repathInterval",
+ "targetX",
+ "targetY"
+ ]
+ },
+ {
+ "name": "NetGhost",
+ "source": "ts",
+ "fields": [],
+ "tag": true
+ },
+ {
+ "name": "OneWayPlatform",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "normal",
+ "type": "Vec2",
+ "default": "(0, 1)"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "normal.x",
+ "normal.y"
+ ]
+ },
+ {
+ "name": "Parent",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "entity",
+ "type": "Entity",
+ "default": "none"
+ }
+ ]
+ },
+ {
+ "name": "ParticleEmitter",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "rate",
+ "type": "number",
+ "default": "10",
+ "range": "≥ 0"
+ },
+ {
+ "key": "burstCount",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0, step 1"
+ },
+ {
+ "key": "burstInterval",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 0"
+ },
+ {
+ "key": "duration",
+ "type": "number",
+ "default": "5",
+ "range": "≥ 0"
+ },
+ {
+ "key": "looping",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "playOnStart",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "maxParticles",
+ "type": "number",
+ "default": "1000",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "lifetimeMin",
+ "type": "number",
+ "default": "5",
+ "range": "≥ 0"
+ },
+ {
+ "key": "lifetimeMax",
+ "type": "number",
+ "default": "5",
+ "range": "≥ 0"
+ },
+ {
+ "key": "shape",
+ "type": "enum",
+ "default": "Cone",
+ "values": [
+ "Point",
+ "Circle",
+ "Rectangle",
+ "Cone"
+ ]
+ },
+ {
+ "key": "shapeRadius",
+ "type": "number",
+ "default": "100",
+ "range": "≥ 0"
+ },
+ {
+ "key": "shapeSize",
+ "type": "Vec2",
+ "default": "(100, 100)"
+ },
+ {
+ "key": "shapeAngle",
+ "type": "number",
+ "default": "25"
+ },
+ {
+ "key": "speedMin",
+ "type": "number",
+ "default": "500"
+ },
+ {
+ "key": "speedMax",
+ "type": "number",
+ "default": "500"
+ },
+ {
+ "key": "angleSpreadMin",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "angleSpreadMax",
+ "type": "number",
+ "default": "360"
+ },
+ {
+ "key": "startSizeMin",
+ "type": "number",
+ "default": "100",
+ "range": "≥ 0"
+ },
+ {
+ "key": "startSizeMax",
+ "type": "number",
+ "default": "100",
+ "range": "≥ 0"
+ },
+ {
+ "key": "endSizeMin",
+ "type": "number",
+ "default": "100",
+ "range": "≥ 0"
+ },
+ {
+ "key": "endSizeMax",
+ "type": "number",
+ "default": "100",
+ "range": "≥ 0"
+ },
+ {
+ "key": "sizeEasing",
+ "type": "enum",
+ "default": "Linear",
+ "values": [
+ "Linear",
+ "EaseIn",
+ "EaseOut",
+ "EaseInOut"
+ ]
+ },
+ {
+ "key": "startColor",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "endColor",
+ "type": "Color",
+ "default": "#ffffff00"
+ },
+ {
+ "key": "colorEasing",
+ "type": "enum",
+ "default": "Linear",
+ "values": [
+ "Linear",
+ "EaseIn",
+ "EaseOut",
+ "EaseInOut"
+ ]
+ },
+ {
+ "key": "rotationMin",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "rotationMax",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "angularVelocityMin",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "angularVelocityMax",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "gravity",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "damping",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0"
+ },
+ {
+ "key": "noiseStrength",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0"
+ },
+ {
+ "key": "noiseFrequency",
+ "type": "number",
+ "default": "0.01",
+ "range": "≥ 0"
+ },
+ {
+ "key": "noiseScrollSpeed",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "noiseOctaves",
+ "type": "number",
+ "default": "1",
+ "range": "1–8, step 1"
+ },
+ {
+ "key": "texture",
+ "type": "Asset<texture>",
+ "default": "none"
+ },
+ {
+ "key": "spriteColumns",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "spriteRows",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "spriteFPS",
+ "type": "number",
+ "default": "10",
+ "range": "≥ 0"
+ },
+ {
+ "key": "spriteLoop",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "blendMode",
+ "type": "enum",
+ "default": "Additive",
+ "values": [
+ "Normal",
+ "Additive",
+ "Multiply",
+ "Screen",
+ "PremultipliedAlpha",
+ "PmaAdditive",
+ "Lighten",
+ "Darken",
+ "Overlay",
+ "None"
+ ]
+ },
+ {
+ "key": "layer",
+ "type": "enum (sortingLayers)",
+ "default": "0",
+ "range": "step 1"
+ },
+ {
+ "key": "material",
+ "type": "Asset<material>",
+ "default": "none"
+ },
+ {
+ "key": "simulationSpace",
+ "type": "enum",
+ "default": "World",
+ "values": [
+ "World",
+ "Local"
+ ]
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "subEmitterTrigger",
+ "type": "enum",
+ "default": "Death",
+ "values": [
+ "Death",
+ "Birth"
+ ]
+ },
+ {
+ "key": "subEmitterChance",
+ "type": "number",
+ "default": "1",
+ "range": "0–1"
+ },
+ {
+ "key": "subEmitterInheritVelocity",
+ "type": "number",
+ "default": "0",
+ "range": "0–1"
+ },
+ {
+ "key": "subEmitter",
+ "type": "Entity",
+ "default": "none"
+ },
+ {
+ "key": "trailEnabled",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "trailWidth",
+ "type": "number",
+ "default": "8",
+ "range": "≥ 0"
+ },
+ {
+ "key": "trailPoints",
+ "type": "number",
+ "default": "6",
+ "range": "2–12, step 1"
+ },
+ {
+ "key": "trailMinDistance",
+ "type": "number",
+ "default": "6",
+ "range": "≥ 0"
+ },
+ {
+ "key": "collisionEnabled",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "collisionFloor",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "collisionBounce",
+ "type": "number",
+ "default": "0.5",
+ "range": "0–1"
+ },
+ {
+ "key": "collisionFriction",
+ "type": "number",
+ "default": "0.1",
+ "range": "0–1"
+ },
+ {
+ "key": "collisionLifetimeLoss",
+ "type": "number",
+ "default": "0",
+ "range": "0–1"
+ },
+ {
+ "key": "colorGradient",
+ "type": "object",
+ "default": "{\"stops\":[]}"
+ },
+ {
+ "key": "sizeCurve",
+ "type": "object",
+ "default": "{\"keys\":[]}"
+ }
+ ]
+ },
+ {
+ "name": "ParticleForceField",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "type",
+ "type": "enum",
+ "default": "Directional",
+ "values": [
+ "Directional",
+ "Point",
+ "Vortex",
+ "Drag"
+ ]
+ },
+ {
+ "key": "strength",
+ "type": "number",
+ "default": "200"
+ },
+ {
+ "key": "radius",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0"
+ },
+ {
+ "key": "direction",
+ "type": "Vec2",
+ "default": "(1, 0)"
+ },
+ {
+ "key": "falloff",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "Perceiver",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "range",
+ "type": "number",
+ "default": "220",
+ "range": "≥ 0"
+ },
+ {
+ "key": "fovDegrees",
+ "type": "number",
+ "default": "360",
+ "range": "0–360"
+ }
+ ],
+ "animatable": [
+ "range",
+ "fovDegrees"
+ ]
+ },
+ {
+ "name": "Perception",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "visible",
+ "type": "boolean",
+ "default": "false",
+ "doc": "A target is seen (runtime, read-only).",
+ "advanced": true
+ },
+ {
+ "key": "distance",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "targetX",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "targetY",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "dirX",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "dirY",
+ "type": "number",
+ "default": "0"
+ }
+ ],
+ "transient": true,
+ "animatable": [
+ "distance",
+ "targetX",
+ "targetY",
+ "dirX",
+ "dirY"
+ ]
+ },
+ {
+ "name": "PerceptionTarget",
+ "source": "ts",
+ "fields": [],
+ "tag": true
+ },
+ {
+ "name": "PolygonCollider",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "vertices",
+ "type": "Vec2[]",
+ "default": "[{\"x\":-0.5,\"y\":-0.5},{\"x\":0.5,\"y\":-0.5},{\"x\":0.5,\"y\":0.5},{\"x\":-0.5,\"y\":0.5}]"
+ },
+ {
+ "key": "radius",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "density",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "friction",
+ "type": "number",
+ "default": "0.3"
+ },
+ {
+ "key": "restitution",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "isSensor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "categoryBits",
+ "type": "number",
+ "default": "1",
+ "advanced": true
+ },
+ {
+ "key": "maskBits",
+ "type": "number",
+ "default": "65535",
+ "advanced": true
+ }
+ ],
+ "animatable": [
+ "radius",
+ "density",
+ "friction",
+ "restitution",
+ "categoryBits",
+ "maskBits"
+ ]
+ },
+ {
+ "name": "PostProcessVolume",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "effects",
+ "type": "array",
+ "default": "empty"
+ },
+ {
+ "key": "isGlobal",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "shape",
+ "type": "string",
+ "default": "\"box\""
+ },
+ {
+ "key": "size",
+ "type": "Vec2",
+ "default": "(5, 5)"
+ },
+ {
+ "key": "priority",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "weight",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "blendDistance",
+ "type": "number",
+ "default": "0"
+ }
+ ],
+ "animatable": [
+ "size.x",
+ "size.y",
+ "priority",
+ "weight",
+ "blendDistance"
+ ]
+ },
+ {
+ "name": "PrismaticJoint",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "connectedEntity",
+ "type": "Entity",
+ "default": "-1"
+ },
+ {
+ "key": "anchorA",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "anchorB",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "axis",
+ "type": "Vec2",
+ "default": "(1, 0)"
+ },
+ {
+ "key": "enableSpring",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "hertz",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "dampingRatio",
+ "type": "number",
+ "default": "0.5"
+ },
+ {
+ "key": "enableLimit",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "lowerTranslation",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "upperTranslation",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "enableMotor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "maxMotorForce",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "motorSpeed",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "collideConnected",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "connectedEntity",
+ "anchorA.x",
+ "anchorA.y",
+ "anchorB.x",
+ "anchorB.y",
+ "axis.x",
+ "axis.y",
+ "hertz",
+ "dampingRatio",
+ "lowerTranslation",
+ "upperTranslation",
+ "maxMotorForce",
+ "motorSpeed"
+ ]
+ },
+ {
+ "name": "Replicated",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "netId",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "owner",
+ "type": "number",
+ "default": "0"
+ }
+ ],
+ "animatable": [
+ "netId",
+ "owner"
+ ]
+ },
+ {
+ "name": "RevoluteJoint",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "connectedEntity",
+ "type": "Entity",
+ "default": "-1"
+ },
+ {
+ "key": "anchorA",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "anchorB",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "enableMotor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "motorSpeed",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "maxMotorTorque",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "enableLimit",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "lowerAngle",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "upperAngle",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "collideConnected",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "connectedEntity",
+ "anchorA.x",
+ "anchorA.y",
+ "anchorB.x",
+ "anchorB.y",
+ "motorSpeed",
+ "maxMotorTorque",
+ "lowerAngle",
+ "upperAngle"
+ ]
+ },
+ {
+ "name": "RigidBody",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "bodyType",
+ "type": "enum",
+ "default": "Dynamic",
+ "values": [
+ "Static",
+ "Kinematic",
+ "Dynamic"
+ ]
+ },
+ {
+ "key": "gravityScale",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "linearDamping",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0",
+ "advanced": true
+ },
+ {
+ "key": "angularDamping",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0",
+ "advanced": true
+ },
+ {
+ "key": "fixedRotation",
+ "type": "boolean",
+ "default": "false",
+ "advanced": true
+ },
+ {
+ "key": "bullet",
+ "type": "boolean",
+ "default": "false",
+ "advanced": true
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "RuntimeOnly",
+ "source": "ts",
+ "fields": [],
+ "tag": true
+ },
+ {
+ "name": "SafeArea",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "applyTop",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "applyBottom",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "applyLeft",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "applyRight",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "SceneOwner",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "scene",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "persistent",
+ "type": "boolean",
+ "default": "false"
+ }
+ ]
+ },
+ {
+ "name": "SegmentCollider",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "point1",
+ "type": "Vec2",
+ "default": "(-0.5, 0)"
+ },
+ {
+ "key": "point2",
+ "type": "Vec2",
+ "default": "(0.5, 0)"
+ },
+ {
+ "key": "density",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "friction",
+ "type": "number",
+ "default": "0.3"
+ },
+ {
+ "key": "restitution",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "isSensor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "categoryBits",
+ "type": "number",
+ "default": "1",
+ "advanced": true
+ },
+ {
+ "key": "maskBits",
+ "type": "number",
+ "default": "65535",
+ "advanced": true
+ }
+ ]
+ },
+ {
+ "name": "ShadowCaster2D",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "size",
+ "type": "Vec2",
+ "default": "(32, 32)",
+ "doc": "Occluder box size in world units (centered on the entity).",
+ "range": "≥ 0"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "size.x",
+ "size.y"
+ ]
+ },
+ {
+ "name": "ShapeRenderer",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "shapeType",
+ "type": "enum",
+ "default": "Circle",
+ "values": [
+ "Circle",
+ "Capsule",
+ "RoundedRect"
+ ]
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "size",
+ "type": "Vec2",
+ "default": "(100, 100)"
+ },
+ {
+ "key": "cornerRadius",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0"
+ },
+ {
+ "key": "layer",
+ "type": "enum (sortingLayers)",
+ "default": "0",
+ "range": "step 1"
+ },
+ {
+ "key": "parallax",
+ "type": "Vec2",
+ "default": "(1, 1)",
+ "doc": "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).",
+ "advanced": true
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "SpineAnimation",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "skeletonPath",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "atlasPath",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "skin",
+ "type": "enum (spineSkins)",
+ "default": "empty"
+ },
+ {
+ "key": "animation",
+ "type": "enum (spineAnimations)",
+ "default": "empty"
+ },
+ {
+ "key": "timeScale",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 0"
+ },
+ {
+ "key": "loop",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "playing",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "flipX",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "flipY",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "layer",
+ "type": "enum (sortingLayers)",
+ "default": "0",
+ "range": "step 1"
+ },
+ {
+ "key": "skeletonScale",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 0"
+ },
+ {
+ "key": "material",
+ "type": "Asset<material>",
+ "default": "none"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "Sprite",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "texture",
+ "type": "Asset<texture>",
+ "default": "none"
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff",
+ "doc": "Tint multiplied into the texture (white = unchanged)."
+ },
+ {
+ "key": "size",
+ "type": "Vec2",
+ "default": "(100, 100)"
+ },
+ {
+ "key": "pivot",
+ "type": "Vec2",
+ "default": "(0.5, 0.5)",
+ "doc": "Anchor point (0–1) the sprite rotates and scales about.",
+ "advanced": true
+ },
+ {
+ "key": "uvOffset",
+ "type": "Vec2",
+ "default": "(0, 0)",
+ "advanced": true
+ },
+ {
+ "key": "uvScale",
+ "type": "Vec2",
+ "default": "(1, 1)",
+ "advanced": true
+ },
+ {
+ "key": "layer",
+ "type": "enum (sortingLayers)",
+ "default": "0",
+ "doc": "Sorting layer — controls draw order across sprites.",
+ "range": "step 1"
+ },
+ {
+ "key": "lit",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Receive 2D lights: Light2D entities light this sprite (flat normal). A custom material overrides this."
+ },
+ {
+ "key": "flipX",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "flipY",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "tileSize",
+ "type": "Vec2",
+ "default": "(0, 0)",
+ "advanced": true
+ },
+ {
+ "key": "tileSpacing",
+ "type": "Vec2",
+ "default": "(0, 0)",
+ "advanced": true
+ },
+ {
+ "key": "parallax",
+ "type": "Vec2",
+ "default": "(1, 1)",
+ "doc": "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).",
+ "advanced": true
+ },
+ {
+ "key": "material",
+ "type": "Asset<material>",
+ "default": "none",
+ "advanced": true
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "color.r",
+ "color.g",
+ "color.b",
+ "color.a",
+ "size.x",
+ "size.y"
+ ]
+ },
+ {
+ "name": "SpriteAnimator",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "clip",
+ "type": "Asset<anim-clip>",
+ "default": "none"
+ },
+ {
+ "key": "speed",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "playing",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "loop",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "currentFrame",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "frameTimer",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "finished",
+ "type": "boolean",
+ "default": "false"
+ }
+ ],
+ "animatable": [
+ "speed",
+ "currentFrame",
+ "frameTimer"
+ ]
+ },
+ {
+ "name": "StateMachineAgent",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "fsm",
+ "type": "Asset<statemachine>",
+ "default": "none"
+ },
+ {
+ "key": "current",
+ "type": "string",
+ "default": "empty",
+ "doc": "Active state (runtime, read-only).",
+ "advanced": true
+ }
+ ]
+ },
+ {
+ "name": "Text",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "content",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "i18nKey",
+ "type": "enum (localeKeys)",
+ "default": "empty",
+ "doc": "Localization key — when set, content is resolved from the Localization catalogs (and re-resolved on locale switch). Leave empty for plain text."
+ },
+ {
+ "key": "font",
+ "type": "Asset<font>",
+ "default": "none",
+ "doc": "A font file this project ships (.ttf / .otf). Overrides Font Family when set; leave empty to use a font the host already has."
+ },
+ {
+ "key": "fontFamily",
+ "type": "string",
+ "default": "\"Arial\"",
+ "doc": "A font the HOST already has (system or page-loaded). Ignored when Font is set."
+ },
+ {
+ "key": "fontSize",
+ "type": "number",
+ "default": "24"
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "align",
+ "type": "enum",
+ "default": "Left",
+ "doc": "Horizontal alignment: within the layout box when the entity has a UINode, else it anchors the text to the entity origin (left/center/right edge).",
+ "values": [
+ "Left",
+ "Center",
+ "Right"
+ ]
+ },
+ {
+ "key": "verticalAlign",
+ "type": "enum",
+ "default": "Top",
+ "doc": "Vertical alignment: within the layout box when the entity has a UINode, else it anchors the text to the entity origin (top/middle/bottom).",
+ "values": [
+ "Top",
+ "Middle",
+ "Bottom"
+ ]
+ },
+ {
+ "key": "wordWrap",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "overflow",
+ "type": "enum",
+ "default": "Visible",
+ "values": [
+ "Visible",
+ "Clip",
+ "Ellipsis"
+ ]
+ },
+ {
+ "key": "lineHeight",
+ "type": "number",
+ "default": "1.2"
+ },
+ {
+ "key": "bold",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "italic",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "strokeColor",
+ "type": "Color",
+ "default": "#000000"
+ },
+ {
+ "key": "strokeWidth",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "shadowColor",
+ "type": "Color",
+ "default": "#000000"
+ },
+ {
+ "key": "shadowBlur",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "shadowOffsetX",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "shadowOffsetY",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "richText",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "renderMode",
+ "type": "enum",
+ "default": "Auto",
+ "values": [
+ "Auto",
+ "Bitmap",
+ "Sdf"
+ ]
+ },
+ {
+ "key": "layer",
+ "type": "number",
+ "default": "0",
+ "doc": "Draw layer for a text standing in the WORLD (no UINode) — read like Sprite/ShapeRenderer layer, so a label can sit in front of the content around it. Ignored inside a Canvas, where the UI render order decides."
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "font",
+ "fontSize",
+ "color.r",
+ "color.g",
+ "color.b",
+ "color.a",
+ "align",
+ "verticalAlign",
+ "overflow",
+ "lineHeight",
+ "strokeColor.r",
+ "strokeColor.g",
+ "strokeColor.b",
+ "strokeColor.a",
+ "strokeWidth",
+ "shadowColor.r",
+ "shadowColor.g",
+ "shadowColor.b",
+ "shadowColor.a",
+ "shadowBlur",
+ "shadowOffsetX",
+ "shadowOffsetY",
+ "renderMode",
+ "layer"
+ ]
+ },
+ {
+ "name": "TextInput",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "value",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "placeholder",
+ "type": "string",
+ "default": "empty"
+ },
+ {
+ "key": "placeholderColor",
+ "type": "Color",
+ "default": "#999999"
+ },
+ {
+ "key": "font",
+ "type": "Asset<font>",
+ "default": "none",
+ "doc": "A font file this project ships (.ttf / .otf). Overrides Font Family when set; leave empty to use a font the host already has."
+ },
+ {
+ "key": "fontFamily",
+ "type": "string",
+ "default": "\"Arial\"",
+ "doc": "A font the HOST already has (system or page-loaded). Ignored when Font is set."
+ },
+ {
+ "key": "fontSize",
+ "type": "number",
+ "default": "16"
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "backgroundColor",
+ "type": "Color",
+ "default": "#262626"
+ },
+ {
+ "key": "padding",
+ "type": "number",
+ "default": "6"
+ },
+ {
+ "key": "maxLength",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "multiline",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "password",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "readOnly",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "focused",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "cursorPos",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "dirty",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "textAlign",
+ "type": "enum",
+ "default": "Left",
+ "doc": "Where the value sits in the field. A single line holds the alignment while it fits, then scrolls to follow the caret.",
+ "values": [
+ "Left",
+ "Center",
+ "Right"
+ ]
+ },
+ {
+ "key": "renderMode",
+ "type": "enum",
+ "default": "Auto",
+ "doc": "Glyph pipeline for the field text — Auto (hinted bitmap when unscaled, SDF once scaled), always Bitmap, or always SDF.",
+ "values": [
+ "Auto",
+ "Bitmap",
+ "Sdf"
+ ]
+ }
+ ],
+ "animatable": [
+ "placeholderColor.r",
+ "placeholderColor.g",
+ "placeholderColor.b",
+ "placeholderColor.a",
+ "font",
+ "fontSize",
+ "color.r",
+ "color.g",
+ "color.b",
+ "color.a",
+ "backgroundColor.r",
+ "backgroundColor.g",
+ "backgroundColor.b",
+ "backgroundColor.a",
+ "padding",
+ "maxLength",
+ "cursorPos",
+ "textAlign",
+ "renderMode"
+ ]
+ },
+ {
+ "name": "ThemeStyle",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "visual",
+ "type": "unknown",
+ "default": "—"
+ },
+ {
+ "key": "text",
+ "type": "unknown",
+ "default": "—"
+ },
+ {
+ "key": "states",
+ "type": "object",
+ "default": "empty"
+ },
+ {
+ "key": "input",
+ "type": "unknown",
+ "default": "—"
+ }
+ ]
+ },
+ {
+ "name": "Tilemap",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "source",
+ "type": "Asset<tilemap>",
+ "default": "none"
+ }
+ ]
+ },
+ {
+ "name": "TilemapLayer",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "cellSize",
+ "type": "Vec2",
+ "default": "(32, 32)"
+ },
+ {
+ "key": "orientation",
+ "type": "enum",
+ "default": "Orthogonal",
+ "doc": "Grid layout: orthogonal, isometric, staggered, or hexagonal.",
+ "values": [
+ "Orthogonal",
+ "Isometric",
+ "Staggered",
+ "Hexagonal"
+ ]
+ },
+ {
+ "key": "hexSideLength",
+ "type": "number",
+ "default": "0",
+ "doc": "Hexagonal side length in px (0 = a regular pointy hex = tileHeight/2). Ignored unless orientation is Hexagonal.",
+ "range": "≥ 0, step 1"
+ },
+ {
+ "key": "staggerAxis",
+ "type": "enum",
+ "default": "Y",
+ "doc": "Stagger axis (staggered/hex): Y shifts rows, X shifts columns.",
+ "values": [
+ "Y",
+ "X"
+ ]
+ },
+ {
+ "key": "staggerIndex",
+ "type": "enum",
+ "default": "Odd",
+ "doc": "Which lines carry the half-cell shift (staggered/hex).",
+ "values": [
+ "Odd",
+ "Even"
+ ]
+ },
+ {
+ "key": "originOffset",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "tileset",
+ "type": "Asset<texture>",
+ "default": "none"
+ },
+ {
+ "key": "tilesetColumns",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "tilesetRows",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "renderLayer",
+ "type": "enum (sortingLayers)",
+ "default": "0",
+ "range": "step 1"
+ },
+ {
+ "key": "tintColor",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "opacity",
+ "type": "number",
+ "default": "1",
+ "doc": "Layer transparency (0 = invisible, 1 = opaque).",
+ "range": "0–1"
+ },
+ {
+ "key": "parallaxFactor",
+ "type": "Vec2",
+ "default": "(1, 1)"
+ },
+ {
+ "key": "visible",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "tintColor.r",
+ "tintColor.g",
+ "tintColor.b",
+ "tintColor.a",
+ "opacity"
+ ]
+ },
+ {
+ "name": "TimelinePlayer",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "timeline",
+ "type": "Asset<timeline>",
+ "default": "none"
+ },
+ {
+ "key": "playing",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "speed",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "wrapMode",
+ "type": "string",
+ "default": "\"once\""
+ },
+ {
+ "key": "finished",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Clip completed (runtime, read-only). Raise Playing to replay.",
+ "advanced": true
+ }
+ ],
+ "animatable": [
+ "speed"
+ ]
+ },
+ {
+ "name": "TrailRenderer",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "time",
+ "type": "number",
+ "default": "0.5",
+ "doc": "Seconds each trail point lives before it fades out of the tail.",
+ "range": "≥ 0"
+ },
+ {
+ "key": "minVertexDistance",
+ "type": "number",
+ "default": "5",
+ "doc": "Min world distance moved before a new trail point is recorded.",
+ "range": "≥ 0"
+ },
+ {
+ "key": "emitting",
+ "type": "boolean",
+ "default": "true",
+ "doc": "Record new points. False = freeze and let the streak fade in place."
+ },
+ {
+ "key": "startWidth",
+ "type": "number",
+ "default": "20",
+ "doc": "Full ribbon width at the head (newest point).",
+ "range": "≥ 0"
+ },
+ {
+ "key": "endWidth",
+ "type": "number",
+ "default": "0",
+ "doc": "Full ribbon width at the tail (oldest point).",
+ "range": "≥ 0"
+ },
+ {
+ "key": "startColor",
+ "type": "Color",
+ "default": "#ffffff",
+ "doc": "Color at the head (newest point)."
+ },
+ {
+ "key": "endColor",
+ "type": "Color",
+ "default": "#ffffff00",
+ "doc": "Color at the tail (oldest point) — usually alpha 0 to fade out."
+ },
+ {
+ "key": "texture",
+ "type": "Asset<texture>",
+ "default": "none"
+ },
+ {
+ "key": "blendMode",
+ "type": "number",
+ "default": "0",
+ "doc": "Blend mode: 0 Normal, 1 Additive (glow), 2 Multiply, …"
+ },
+ {
+ "key": "layer",
+ "type": "enum (sortingLayers)",
+ "default": "0",
+ "doc": "Sorting layer — controls draw order across renderables.",
+ "range": "step 1"
+ },
+ {
+ "key": "material",
+ "type": "Asset<material>",
+ "default": "none",
+ "advanced": true
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "startColor.r",
+ "startColor.g",
+ "startColor.b",
+ "startColor.a",
+ "endColor.r",
+ "endColor.g",
+ "endColor.b",
+ "endColor.a"
+ ]
+ },
+ {
+ "name": "Transform",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "position",
+ "type": "Vec3",
+ "default": "(0, 0, 0)",
+ "doc": "Local position in world units, relative to the parent.",
+ "replicated": true
+ },
+ {
+ "key": "rotation",
+ "type": "Quat",
+ "default": "(0, 0, 0, 1)",
+ "doc": "Rotation about the Z axis, in degrees.",
+ "replicated": true
+ },
+ {
+ "key": "scale",
+ "type": "Vec3",
+ "default": "(1, 1, 1)",
+ "doc": "Local scale per axis (1 = original size; negative flips).",
+ "replicated": true
+ },
+ {
+ "key": "worldPosition",
+ "type": "Vec3",
+ "default": "(0, 0, 0)",
+ "readonly": true
+ },
+ {
+ "key": "worldRotation",
+ "type": "Quat",
+ "default": "(0, 0, 0, 1)",
+ "readonly": true
+ },
+ {
+ "key": "worldScale",
+ "type": "Vec3",
+ "default": "(1, 1, 1)",
+ "readonly": true
+ }
+ ],
+ "animatable": [
+ "position.x",
+ "position.y",
+ "position.z",
+ "rotation.z",
+ "scale.x",
+ "scale.y",
+ "scale.z"
+ ]
+ },
+ {
+ "name": "UIController",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "controllers",
+ "type": "array",
+ "default": "empty"
+ }
+ ]
+ },
+ {
+ "name": "UIDialog",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "closeOnEscape",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "closeOnBackdrop",
+ "type": "boolean",
+ "default": "true"
+ }
+ ]
+ },
+ {
+ "name": "UIDropdown",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "options",
+ "type": "array",
+ "default": "empty"
+ },
+ {
+ "key": "selectedIndex",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "optionHeight",
+ "type": "number",
+ "default": "32"
+ },
+ {
+ "key": "label",
+ "type": "Entity",
+ "default": "none"
+ }
+ ],
+ "animatable": [
+ "selectedIndex",
+ "optionHeight",
+ "label"
+ ]
+ },
+ {
+ "name": "UIGear",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "bindings",
+ "type": "array",
+ "default": "empty"
+ }
+ ]
+ },
+ {
+ "name": "UIInteraction",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "hovered",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "pressed",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "justPressed",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "justReleased",
+ "type": "boolean",
+ "default": "false"
+ }
+ ],
+ "transient": true
+ },
+ {
+ "name": "UIMask",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "mode",
+ "type": "enum",
+ "default": "Scissor",
+ "values": [
+ "Scissor",
+ "Stencil"
+ ]
+ },
+ {
+ "key": "alphaCutoff",
+ "type": "number",
+ "default": "0",
+ "doc": "Stencil only: above 0, clip to the mask sprite's shape instead of its box."
+ }
+ ]
+ },
+ {
+ "name": "UINode",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "position",
+ "type": "enum",
+ "default": "Relative",
+ "values": [
+ "Relative",
+ "Absolute"
+ ]
+ },
+ {
+ "key": "display",
+ "type": "enum",
+ "default": "Flex",
+ "doc": "None removes this node and its whole subtree from layout, rendering and input.",
+ "values": [
+ "Flex",
+ "None"
+ ]
+ },
+ {
+ "key": "opacity",
+ "type": "number",
+ "default": "1",
+ "doc": "Subtree opacity, multiplied down the tree. Fades this node and everything under it.",
+ "range": "0–1"
+ },
+ {
+ "key": "pointerEvents",
+ "type": "enum",
+ "default": "Auto",
+ "doc": "None makes this node and its subtree transparent to the pointer — hits pass through to what is behind.",
+ "values": [
+ "Auto",
+ "None"
+ ]
+ },
+ {
+ "key": "width",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "height",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "minWidth",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "minHeight",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "maxWidth",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "maxHeight",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "flexGrow",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "flexShrink",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "flexBasis",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "alignSelf",
+ "type": "enum",
+ "default": "Auto",
+ "values": [
+ "Auto",
+ "Start",
+ "Center",
+ "End",
+ "Stretch"
+ ]
+ },
+ {
+ "key": "marginLeft",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":0}"
+ },
+ {
+ "key": "marginTop",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":0}"
+ },
+ {
+ "key": "marginRight",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":0}"
+ },
+ {
+ "key": "marginBottom",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":0}"
+ },
+ {
+ "key": "insetLeft",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "insetTop",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "insetRight",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ },
+ {
+ "key": "insetBottom",
+ "type": "Dimension",
+ "default": "{\"value\":0,\"unit\":2}"
+ }
+ ]
+ },
+ {
+ "name": "UIScroll",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "content",
+ "type": "Entity",
+ "default": "none",
+ "doc": "The child that scrolls inside this node. Leave empty to use the first child."
+ },
+ {
+ "key": "horizontal",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "vertical",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "movement",
+ "type": "enum",
+ "default": "Clamped",
+ "doc": "Clamped stops at the ends; Elastic overshoots and springs back.",
+ "values": [
+ "Clamped",
+ "Elastic"
+ ]
+ },
+ {
+ "key": "wheelSpeed",
+ "type": "number",
+ "default": "1",
+ "range": "≥ 0"
+ },
+ {
+ "key": "dragScroll",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "decelerationRate",
+ "type": "number",
+ "default": "0.135",
+ "doc": "Fraction of flick velocity kept per second. 0 stops on release.",
+ "range": "0–1"
+ }
+ ]
+ },
+ {
+ "name": "UISlider",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "min",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "max",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "step",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "value",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "fill",
+ "type": "Entity",
+ "default": "none"
+ },
+ {
+ "key": "handle",
+ "type": "Entity",
+ "default": "none"
+ }
+ ],
+ "animatable": [
+ "min",
+ "max",
+ "step",
+ "value",
+ "fill",
+ "handle"
+ ]
+ },
+ {
+ "name": "UIToggle",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "isOn",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "check",
+ "type": "Entity",
+ "default": "none"
+ }
+ ],
+ "animatable": [
+ "check"
+ ]
+ },
+ {
+ "name": "UIVisual",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "visualType",
+ "type": "enum",
+ "default": "None",
+ "values": [
+ "None",
+ "SolidColor",
+ "Image",
+ "NineSlice",
+ "Tiled",
+ "Filled"
+ ]
+ },
+ {
+ "key": "texture",
+ "type": "Asset<texture>",
+ "default": "none"
+ },
+ {
+ "key": "color",
+ "type": "Color",
+ "default": "#ffffff"
+ },
+ {
+ "key": "fit",
+ "type": "enum",
+ "default": "Fill",
+ "doc": "How the image fits its box: Fill stretches, Contain letterboxes it whole, Cover fills and crops.",
+ "values": [
+ "Fill",
+ "Contain",
+ "Cover"
+ ]
+ },
+ {
+ "key": "uvOffset",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "uvScale",
+ "type": "Vec2",
+ "default": "(1, 1)"
+ },
+ {
+ "key": "sliceBorder",
+ "type": "Vec4",
+ "default": "(0, 0, 0, 0)"
+ },
+ {
+ "key": "tileSize",
+ "type": "Vec2",
+ "default": "(32, 32)"
+ },
+ {
+ "key": "fillMethod",
+ "type": "enum",
+ "default": "Horizontal",
+ "values": [
+ "Horizontal",
+ "Vertical",
+ "Radial360",
+ "Radial90",
+ "Radial180"
+ ]
+ },
+ {
+ "key": "fillOrigin",
+ "type": "enum",
+ "default": "Left",
+ "values": [
+ "Left",
+ "Right",
+ "Bottom",
+ "Top"
+ ]
+ },
+ {
+ "key": "fillAmount",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "material",
+ "type": "Asset<material>",
+ "default": "none"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "color.r",
+ "color.g",
+ "color.b",
+ "color.a",
+ "fillAmount"
+ ]
+ },
+ {
+ "name": "Velocity",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "linear",
+ "type": "Vec3",
+ "default": "(0, 0, 0)",
+ "replicated": true
+ },
+ {
+ "key": "angular",
+ "type": "Vec3",
+ "default": "(0, 0, 0)",
+ "replicated": true
+ }
+ ]
+ },
+ {
+ "name": "Video",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "source",
+ "type": "Asset<video>",
+ "default": "none"
+ },
+ {
+ "key": "autoplay",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "loop",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "muted",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "volume",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "playbackRate",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "fitSize",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "volume",
+ "playbackRate"
+ ]
+ },
+ {
+ "name": "WeldJoint",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "connectedEntity",
+ "type": "Entity",
+ "default": "-1"
+ },
+ {
+ "key": "anchorA",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "anchorB",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "linearHertz",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "angularHertz",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "linearDampingRatio",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "angularDampingRatio",
+ "type": "number",
+ "default": "1"
+ },
+ {
+ "key": "collideConnected",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "connectedEntity",
+ "anchorA.x",
+ "anchorA.y",
+ "anchorB.x",
+ "anchorB.y",
+ "linearHertz",
+ "angularHertz",
+ "linearDampingRatio",
+ "angularDampingRatio"
+ ]
+ },
+ {
+ "name": "WheelJoint",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "connectedEntity",
+ "type": "Entity",
+ "default": "-1"
+ },
+ {
+ "key": "anchorA",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "anchorB",
+ "type": "Vec2",
+ "default": "(0, 0)"
+ },
+ {
+ "key": "axis",
+ "type": "Vec2",
+ "default": "(0, 1)"
+ },
+ {
+ "key": "enableSpring",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "hertz",
+ "type": "number",
+ "default": "5"
+ },
+ {
+ "key": "dampingRatio",
+ "type": "number",
+ "default": "0.7"
+ },
+ {
+ "key": "enableLimit",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "lowerTranslation",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "upperTranslation",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "enableMotor",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "maxMotorTorque",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "motorSpeed",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "collideConnected",
+ "type": "boolean",
+ "default": "false"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "connectedEntity",
+ "anchorA.x",
+ "anchorA.y",
+ "anchorB.x",
+ "anchorB.y",
+ "axis.x",
+ "axis.y",
+ "hertz",
+ "dampingRatio",
+ "lowerTranslation",
+ "upperTranslation",
+ "maxMotorTorque",
+ "motorSpeed"
+ ]
+ }
+ ]
+}
diff --git a/package.json b/package.json
index 6447a6968..2fd9cc53d 100644
--- a/package.json
+++ b/package.json
@@ -17,7 +17,7 @@
"emsdk:setup": "node build-tools/toolchain/setup-emsdk.js",
"asset-meta": "node tools/asset-meta.js",
"migrate-asset-refs": "node tools/migrate-asset-refs.js",
- "verify": "pnpm --filter ./sdk exec tsc --noEmit && node tools/api-surface.mjs --check && node tools/check-cycles.mjs && node tools/check-layers.mjs && node tools/check-project-settings.mjs && node tools/check-workflows.mjs",
+ "verify": "pnpm --filter ./sdk exec tsc --noEmit && node tools/api-surface.mjs --check && node tools/check-cycles.mjs && node tools/check-layers.mjs && node tools/check-project-settings.mjs && node tools/check-workflows.mjs && node tools/component-reference.mjs --check",
"perf": "node tools/perf-guard.mjs --check",
"prepare": "git config core.hooksPath .githooks || true"
},
diff --git a/tools/component-reference.mjs b/tools/component-reference.mjs
new file mode 100644
index 000000000..15d59859e
--- /dev/null
+++ b/tools/component-reference.mjs
@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file component-reference.mjs
+ * @brief The component reference the docs render, generated from the engine's
+ * own component registry.
+ *
+ * Every component a game can author, with its fields, types and authoring
+ * defaults, is already described by the registry the editor's Details panel
+ * reads: `getComponentRegistry()` returns each definition's merged defaults
+ * (C++ ctor values with the `editor_default=` overrides applied — what you
+ * actually get when you add the component), plus the asset / entity / colour /
+ * enum / range / tooltip metadata authored at the C++ `ES_PROPERTY` site. Hand
+ * a writer that list and it drifts the first time someone adds a field; derive
+ * it and it cannot.
+ *
+ * Run: node tools/component-reference.mjs --update (refresh the snapshot)
+ * node tools/component-reference.mjs --check (CI: exit 1 on drift)
+ *
+ * `--update` loads the built SDK, so build it first:
+ * pnpm --filter ./sdk exec rollup -c
+ *
+ * `--check` needs no build. It enumerates the component NAMES straight from
+ * source — every `defineComponent` / `defineBuiltin` / `defineTag` call site
+ * plus every key of the EHT-generated COMPONENT_META — and fails when that set
+ * disagrees with the snapshot, or when the docs' curated table (which supplies
+ * each component's category and the guide that explains it) has drifted from
+ * either. When a built SDK happens to be present it additionally re-derives the
+ * field data and diffs that too, so a changed field is caught wherever the
+ * stronger check can run.
+ */
+import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(here, '..');
+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');
+
+const mode = process.argv[2];
+if (mode !== '--check' && mode !== '--update') {
+ console.error('usage: node tools/component-reference.mjs --check | --update');
+ process.exit(2);
+}
+
+// ── enumerating the components ───────────────────────────────────────────────
+
+function tsFiles(dir) {
+ const out = [];
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
+ const p = join(dir, e.name);
+ if (e.isDirectory()) out.push(...tsFiles(p));
+ else if (e.name.endsWith('.ts') && !e.name.endsWith('.test.ts') && !e.name.endsWith('.d.ts')) out.push(p);
+ }
+ return out;
+}
+
+/** Comments hold example code (`defineComponent('Patrol', …)`) that would
+ * otherwise register as a component that does not exist. */
+const stripComments = (s) => s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '');
+
+/**
+ * Component names, from source alone — no SDK build required.
+ *
+ * Matches the assignment, not the bare call: every real registration is
+ * `export const X = defineComponent(…)`, while the strings that merely *mention*
+ * the call are prose — a `defineComponent('MyThing', …)` inside an error message
+ * teaching the argument order is not a component, and comment-stripping alone
+ * does not reach it.
+ */
+function namesFromSource() {
+ const names = new Set();
+ for (const f of tsFiles(SDK_SRC)) {
+ const src = stripComments(readFileSync(f, 'utf8'));
+ for (const m of src.matchAll(/=\s*define(?:Component|Builtin|Tag)(?:<[^>]*>)?\(\s*'([A-Za-z0-9_]+)'/g)) {
+ names.add(m[1]);
+ }
+ }
+ // ensureBuiltinComponentsRegistered() registers every COMPONENT_META key,
+ // typed const or not, so the generated metadata is part of the set.
+ const gen = readFileSync(join(SDK_SRC, 'ecs', 'component.generated.ts'), 'utf8');
+ const meta = gen.slice(gen.indexOf('export const COMPONENT_META'));
+ for (const m of meta.matchAll(/^ {4}([A-Za-z0-9_]+): \{$/gm)) names.add(m[1]);
+ return [...names].sort();
+}
+
+// ── describing one component ─────────────────────────────────────────────────
+
+const isVec = (v, ...keys) => {
+ const k = Object.keys(v);
+ return k.length === keys.length && keys.every((x) => k.includes(x));
+};
+
+function typeOf(def, key, value) {
+ const asset = def.assetFields?.find((a) => a.field === key);
+ if (asset) return `Asset<${asset.type}>`;
+ if (def.entityFields?.includes(key)) return 'Entity';
+ if (def.colorKeys?.includes(key)) return 'Color';
+ const meta = def.fieldMeta?.[key];
+ if (meta?.enum) return 'enum';
+ if (meta?.enumSource) return `enum (${meta.enumSource})`;
+ if (value === null || value === undefined) return 'unknown';
+ if (Array.isArray(value)) {
+ if (value.length === 0) return 'array';
+ return `${typeOf(def, key, value[0])}[]`;
+ }
+ switch (typeof value) {
+ case 'boolean': return 'boolean';
+ case 'number': return 'number';
+ case 'string': return 'string';
+ case 'object':
+ if (isVec(value, 'x', 'y')) return 'Vec2';
+ if (isVec(value, 'x', 'y', 'z')) return 'Vec3';
+ // A quaternion and a vec4 have the same shape; only the field's meaning
+ // tells them apart, and rotation is the one the engine stores as a quat.
+ if (isVec(value, 'x', 'y', 'z', 'w')) return /rotation/i.test(key) ? 'Quat' : 'Vec4';
+ if (isVec(value, 'r', 'g', 'b', 'a')) return 'Color';
+ if (isVec(value, 'top', 'right', 'bottom', 'left')) return 'Padding';
+ if (isVec(value, 'value', 'unit')) return 'Dimension';
+ return 'object';
+ default: return typeof value;
+ }
+}
+
+const num = (n) => (Number.isInteger(n) ? String(n) : String(Number(n.toFixed(4))));
+
+function formatDefault(def, key, value, type) {
+ if (type.startsWith('Asset<') || type === 'Entity') return value ? String(value) : 'none';
+ const meta = def.fieldMeta?.[key];
+ if (meta?.enum) {
+ const hit = meta.enum.find((o) => o.value === value);
+ return hit ? hit.label : String(value);
+ }
+ if (value === null || value === undefined) return '—';
+ if (Array.isArray(value)) return value.length ? JSON.stringify(value) : 'empty';
+ switch (typeof value) {
+ case 'boolean': return String(value);
+ case 'number': return num(value);
+ case 'string': return value === '' ? 'empty' : `"${value}"`;
+ case 'object': {
+ if (type === 'Color') {
+ const hex = (c) => Math.round(Math.max(0, Math.min(1, c)) * 255).toString(16).padStart(2, '0');
+ return `#${hex(value.r)}${hex(value.g)}${hex(value.b)}${value.a === 1 ? '' : hex(value.a)}`;
+ }
+ if (type === 'Vec2' || type === 'Vec3' || type === 'Vec4' || type === 'Quat') {
+ // Component order, not key order: the engine stores a quaternion as
+ // {w,x,y,z}, and printing that verbatim reads as x=1 for the identity.
+ const order = ['x', 'y', 'z', 'w'].filter((k) => k in value);
+ return `(${order.map((k) => num(value[k])).join(', ')})`;
+ }
+ const json = JSON.stringify(value);
+ return json === '{}' ? 'empty' : json;
+ }
+ default: return String(value);
+ }
+}
+
+function range(meta) {
+ if (!meta) return undefined;
+ const { min, max, step } = meta;
+ if (min === undefined && max === undefined && step === undefined) return undefined;
+ const parts = [];
+ if (min !== undefined && max !== undefined) parts.push(`${num(min)}–${num(max)}`);
+ else if (min !== undefined) parts.push(`≥ ${num(min)}`);
+ else if (max !== undefined) parts.push(`≤ ${num(max)}`);
+ if (step !== undefined) parts.push(`step ${num(step)}`);
+ return parts.join(', ');
+}
+
+function describe(name, def) {
+ const defaults = def._default ?? {};
+ const keys = Object.keys(defaults);
+ const fields = keys.map((key) => {
+ const value = defaults[key];
+ const meta = def.fieldMeta?.[key];
+ const type = typeOf(def, key, value);
+ const f = { key, type, default: formatDefault(def, key, value, type) };
+ if (meta?.tooltip) f.doc = meta.tooltip;
+ const r = range(meta);
+ if (r) f.range = r;
+ if (meta?.enum) f.values = meta.enum.map((o) => o.label);
+ if (def.readonlyFields?.includes(key)) f.readonly = true;
+ if (def.replicatedFields?.includes(key)) f.replicated = true;
+ if (meta?.advanced) f.advanced = true;
+ return f;
+ });
+ const c = { name, source: def._builtin ? 'cpp' : 'ts', fields };
+ if (keys.length === 0) c.tag = true;
+ if (def.transient) c.transient = true;
+ if (def.animatableFields?.length) c.animatable = def.animatableFields;
+ return c;
+}
+
+async function snapshotFromSdk() {
+ if (!existsSync(SDK_DIST)) {
+ throw new Error(
+ `no built SDK at ${SDK_DIST}\n build it first: pnpm --filter ./sdk exec rollup -c`,
+ );
+ }
+ // The node entry registers every engine component at module load and needs no
+ // wasm — loading the module IS the enumeration.
+ const sdk = await import(pathToFileURL(SDK_DIST).href);
+ const reg = sdk.getComponentRegistry();
+ const components = [...reg.keys()].sort().map((n) => describe(n, reg.get(n)));
+ return { generatedBy: 'tools/component-reference.mjs', abiLayoutHash: sdk.ABI_LAYOUT_HASH ?? null, components };
+}
+
+// ── the curated half ─────────────────────────────────────────────────────────
+
+/** Component names the docs' curated table claims, without parsing TypeScript:
+ * each entry starts a line as ` Name: {`. */
+function curatedNames() {
+ if (!existsSync(CURATED)) return null;
+ const src = readFileSync(CURATED, '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)) });
+
+if (mode === '--update') {
+ const snap = await snapshotFromSdk();
+ 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 curated = curatedNames();
+ if (curated) {
+ const d = diff(curated, snap.components.map((c) => c.name));
+ 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(', ')}`);
+ }
+ process.exit(0);
+}
+
+// --check
+if (!existsSync(SNAPSHOT)) {
+ console.error(`component-reference: no snapshot at ${SNAPSHOT} — run --update`);
+ process.exit(1);
+}
+const snap = JSON.parse(readFileSync(SNAPSHOT, 'utf8'));
+const snapNames = snap.components.map((c) => c.name).sort();
+const problems = [];
+
+const fromSource = namesFromSource();
+const dSrc = diff(snapNames, fromSource);
+for (const n of dSrc.missing) problems.push(`component "${n}" exists in the SDK but is not in the reference snapshot`);
+for (const n of dSrc.extra) problems.push(`reference snapshot has "${n}", which the SDK no longer defines`);
+
+const curated = curatedNames();
+if (curated === null) problems.push(`missing curated table ${CURATED}`);
+else {
+ const dCur = diff(curated, snapNames);
+ for (const n of dCur.missing) problems.push(`component "${n}" has no entry in componentDocs.ts (category + where it is explained)`);
+ for (const n of dCur.extra) problems.push(`componentDocs.ts describes "${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)) {
+ const fresh = await snapshotFromSdk();
+ const a = JSON.stringify(fresh.components), b = JSON.stringify(snap.components);
+ if (a !== b) {
+ const byName = new Map(snap.components.map((c) => [c.name, JSON.stringify(c)]));
+ for (const c of fresh.components) {
+ const was = byName.get(c.name);
+ if (was && was !== JSON.stringify(c)) problems.push(`"${c.name}" changed — run --update`);
+ }
+ if (!problems.length) problems.push('the reference snapshot is stale — run --update');
+ }
+ deep = 'names and field data';
+}
+
+if (problems.length) {
+ console.error(`component-reference: ${problems.length} problem(s) (checked ${deep})`);
+ for (const p of problems) console.error(` ${p}`);
+ console.error('\n refresh with: pnpm --filter ./sdk exec rollup -c && node tools/component-reference.mjs --update');
+ process.exit(1);
+}
+console.log(`component-reference: ${snapNames.length} components clean (checked ${deep}).`);