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.

17.1 KB
Raw Blame
// 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, statSync } from 'node:fs';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { dirname, join, resolve } from 'node:path';
import { componentNamesFromSource } from './lib/componentNames.mjs';
import { newestSource } from './lib/engineBuild.mjs';

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 DOC_PAGES = join(ROOT, 'docs', 'astro', 'src', 'content', 'docs');
// The editor's Details panel links each component header at its reference entry;
// the address is derived here so the two can never point at different pages. The
// editor is an optional submodule, so this is checked when there is one to check.
const EDITOR_LINKS = join(ROOT, 'desktop', 'src', 'engine', 'componentDocs.generated.ts');
const HAS_EDITOR = existsSync(join(ROOT, 'desktop', 'package.json'));

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 ───────────────────────────────────────────────

// The enumerator is shared with check-inspector-door, which refuses a component
// name written as a literal in the Details panel's render path. One definition,
// so a component cannot be known to one check and invisible to the other.
const namesFromSource = componentNamesFromSource;

// ── 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();
}

/** Where each entry sends a reader: the guide, and the heading in each locale. */
function curatedTargets() {
  if (!existsSync(CURATED)) return [];
  const src = readFileSync(CURATED, 'utf8');
  const out = [];
  for (const m of src.matchAll(/^ {2}([A-Za-z0-9_]+): \{(.*)$/gm)) {
    const doc = /doc: '([^']+)'/.exec(m[2]);
    if (!doc) continue;
    out.push({
      name: m[1],
      doc: doc[1],
      anchor: /anchor: '([^']*)'/.exec(m[2])?.[1],
      anchorZh: /anchorZh: '([^']*)'/.exec(m[2])?.[1],
    });
  }
  return out;
}

/** GitHub's heading-slug rule, which is what the site gives its headings: drop
 *  all but letters, digits, `-` and `_`, then each surviving space becomes a
 *  hyphen — "Text & code" is `text--code`, with two. A Chinese heading slugs to
 *  its own characters, never to the English page's slug. */
const slugOf = (heading) =>
  heading
    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
    .replace(/[`*]/g, '')
    .toLowerCase()
    .replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, '')
    .trim()
    .replace(/ /g, '-');

const headingCache = new Map();
/** The anchors one guide offers. Fenced blocks are skipped: a shell comment is
 *  not a heading. */
function headingSlugs(file) {
  let slugs = headingCache.get(file);
  if (slugs) return slugs;
  slugs = new Set();
  let fenced = false;
  for (const line of readFileSync(file, 'utf8').split('\n')) {
    if (/^\s*(```|~~~)/.test(line)) fenced = !fenced;
    else if (!fenced) {
      const h = /^#{2,6}\s+(.+?)\s*$/.exec(line);
      if (h) slugs.add(slugOf(h[1]));
    }
  }
  headingCache.set(file, slugs);
  return slugs;
}

/** name -> category, read from the same curated table. */
function curatedCategories() {
  const src = readFileSync(CURATED, 'utf8');
  const out = {};
  for (const m of src.matchAll(/^ {2}([A-Za-z0-9_]+): \{ category: '([a-z]+)'/gm)) out[m[1]] = m[2];
  return out;
}

/** The editor's link table: component -> path under the docs root. */
function editorLinksSource(names) {
  const cats = curatedCategories();
  const rows = names
    .map((n) => `  ${/^[A-Za-z_][A-Za-z0-9_]*$/.test(n) ? n : `'${n}'`}: 'reference/components/${cats[n]}/#${n.toLowerCase()}',`)
    .join('\n');
  return `// Generated by tools/component-reference.mjs — do not edit. Run --update.
//
// Where the manual documents each component, so the Details panel header can
// link straight there: the question a component's fields provoke is asked while
// looking at them, not while browsing a sidebar.
export const COMPONENT_DOC_PATHS: Readonly<Record<string, string>> = {
${rows}
};
`;
}

/** Component names the editor link table carries. */
function editorLinkNames() {
  if (!existsSync(EDITOR_LINKS)) return null;
  const src = readFileSync(EDITOR_LINKS, 'utf8');
  return [...src.matchAll(/^ {2}'?([A-Za-z0-9_]+)'?: '/gm)].map((m) => m[1]).sort();
}

// ── run ──────────────────────────────────────────────────────────────────────

const diff = (a, b) => ({ missing: b.filter((x) => !a.includes(x)), extra: a.filter((x) => !b.includes(x)) });

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 names = snap.components.map((c) => c.name);
  const curated = curatedNames();
  if (curated) {
    const d = diff(curated, names);
    if (d.missing.length) console.log(`  still to describe in componentDocs.ts: ${d.missing.join(', ')}`);
    if (d.extra.length) console.log(`  componentDocs.ts names components that no longer exist: ${d.extra.join(', ')}`);
    if (!d.missing.length && !d.extra.length) {
      if (HAS_EDITOR) {
        writeFileSync(EDITOR_LINKS, editorLinksSource(names));
        console.log(`  wrote the editor's link table (${names.length} entries)`);
      } else {
        console.log('  editor link table NOT written — no editor checkout to write it into');
      }
    } else {
      console.log("  editor link table NOT written — describe the components above first");
    }
  }
  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`);
}

// Where those entries send a reader. The built site's link check knows this too,
// but it needs the site built and so only runs from the docs deploy — which a
// release calls, making a dead anchor a failure at the moment of shipping.
for (const t of curatedTargets()) {
  for (const [locale, rel, anchor] of [
    ['en', `${t.doc}.mdx`, t.anchor],
    ['zh-cn', join('zh-cn', `${t.doc}.mdx`), t.anchorZh],
  ]) {
    const file = join(DOC_PAGES, rel);
    if (!existsSync(file)) {
      problems.push(`componentDocs.ts sends "${t.name}" to ${locale} ${t.doc}, which is not a page`);
      continue;
    }
    if (anchor && !headingSlugs(file).has(anchor)) {
      problems.push(`"${t.name}" links ${locale} ${t.doc}#${anchor}, which is not a heading there`);
    }
  }
}

const links = HAS_EDITOR ? editorLinkNames() : undefined;
if (links === undefined) {
  console.log("component-reference: no editor checkout — its doc-link table was not checked.");
} else if (links === null) problems.push(`missing the editor's link table ${EDITOR_LINKS}`);
else {
  const dLink = diff(links, snapNames);
  for (const n of dLink.missing) problems.push(`the editor's Details panel has no doc link for "${n}"`);
  for (const n of dLink.extra) problems.push(`the editor links docs for "${n}", which is not a component`);
}

// The strongest check, where a built SDK makes it possible — and only while that
// build is newer than what it came from: a stale one answers about components
// nobody has. Not having checked is reported, never rounded down to a pass.
const distAt = existsSync(SDK_DIST) ? statSync(SDK_DIST).mtimeMs : 0;
const newestTs = newestSource(ROOT, ['sdk/src'], /\.ts$/);
const distIsCurrent = distAt > 0 && newestTs.at <= distAt;
if (distAt > 0 && !distIsCurrent) {
  console.log(`component-reference: the built SDK predates ${newestTs.file} — field data NOT checked.`
    + '\n  build it:  pnpm --filter ./sdk build');
}
let deep = distAt > 0 ? 'names only (the built SDK is stale)' : 'names only (no built SDK)';
if (distIsCurrent) {
  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}).`);