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.

fix(engine): a component declared the wrong way says so, at the declaration

yhh52c602c8a701
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.ts
index 538504bdb..480ab9b41 100644
--- a/desktop/electron/extractSchemas.ts
+++ b/desktop/electron/extractSchemas.ts
@@ -259,9 +259,22 @@ export async function extractProjectSchemas(
const declared = await mod.__extract();
// Deterministic output throughout — the artifact is compared byte-wise by
// the incremental cache and read by humans in diffs.
- const schemas = [...declared.components.values()]
- .map(toSchema)
- .sort((a, b) => a.name.localeCompare(b.name));
+ // A declaration whose name is not a string cannot be sorted, serialized or
+ // looked up, and the sort is where it used to surface — as
+ // "e.name.localeCompare is not a function", a stack away from the call that
+ // caused it and naming neither the component nor the mistake. Newer SDKs
+ // refuse it at defineComponent; a project pinned to an older one still gets
+ // told which declaration is the bad one instead of a stray TypeError.
+ const schemas = [...declared.components.values()].map(toSchema);
+ const unnamed = schemas.find((s) => typeof s.name !== 'string' || s.name === '');
+ if (unnamed) {
+ throw new Error(
+ `a component was declared without a string name (got ${typeof unnamed.name}). `
+ + "defineComponent takes the NAME first and the defaults second — defineComponent('MyThing', "
+ + '{ speed: 100 }).',
+ );
+ }
+ schemas.sort((a, b) => a.name.localeCompare(b.name));
const actions = declared.actions
.map((a) => normalizeAction(a))
.sort((a, b) => a.name.localeCompare(b.name));
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index d482a137c..f14e17a4a 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -219,6 +219,31 @@ function createComponentDef<T extends object>(
defaults: T,
metadata?: ComponentMetadata,
): ComponentDef<T> {
+ // TypeScript already refuses the wrong shapes — but a project's declarations
+ // are BUNDLED, not type-checked, on the path the editor extracts schemas
+ // through. So `defineComponent({ name: 'Piece', fields: {...} })`, the shape
+ // this reads like, sails through and stores an OBJECT as the component's
+ // name. Nothing notices until something sorts by it, a stack away and a
+ // second later, as "e.name.localeCompare is not a function" — naming neither
+ // the component nor the call. Say it here, where the mistake is.
+ if (typeof name !== 'string' || name === '') {
+ const got = name === null ? 'null'
+ : Array.isArray(name) ? 'an array'
+ : typeof name === 'object' ? `an object with keys ${Object.keys(name as object).join(', ')}`
+ : `${typeof name} ${JSON.stringify(name)}`;
+ throw new Error(
+ `defineComponent takes the NAME first and the defaults second — defineComponent('MyThing', `
+ + `{ speed: 100 }) — but was given ${got}. Each field's inspector control comes from the TYPE `
+ + 'of its default value, so the second argument is real values (speed: 100), not a description '
+ + "of them ({ speed: 'number' }).",
+ );
+ }
+ if (defaults === null || typeof defaults !== 'object') {
+ throw new Error(
+ `Component "${name}": the second argument is the defaults OBJECT — defineComponent('${name}', `
+ + `{ speed: 100 }) — but was given ${defaults === undefined ? 'nothing' : JSON.stringify(defaults)}.`,
+ );
+ }
const keyInfo = classifyKeys(defaults);
const defaultsRec = defaults as Record<string, unknown>;
// A replicated name that matches no field would silently sync nothing — the
diff --git a/sdk/tests/component.test.ts b/sdk/tests/component.test.ts
index 3ffd0daef..05870540d 100644
--- a/sdk/tests/component.test.ts
+++ b/sdk/tests/component.test.ts
@@ -334,3 +334,49 @@ describe('Field metadata (editor presentation policy)', () => {
expect(getComponentFieldMeta('Nonexistent')).toEqual({});
});
});
+
+/**
+ * A project's declarations are BUNDLED, not type-checked, on the path the editor
+ * extracts schemas through — so a call TypeScript would have refused reaches
+ * runtime intact. `defineComponent({ name: 'Piece', fields: {...} })` is the
+ * shape the API reads like, and it used to store that whole object as the
+ * component's NAME. Nothing noticed until the extractor sorted by it, a stack
+ * away, as "e.name.localeCompare is not a function" — naming neither the
+ * component nor the call. One dogfood run lost twenty minutes to it and came out
+ * believing the system scheduler was broken.
+ */
+describe('defineComponent refuses a call TypeScript would have caught', () => {
+ it('names the signature when handed the options-object form', () => {
+ expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)(
+ { name: 'Piece', fields: { hp: 'number' } },
+ )).toThrow(/takes the NAME first/);
+ // And says which keys it actually got, so the caller sees their own object.
+ expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)(
+ { name: 'Piece', fields: { hp: 'number' } },
+ )).toThrow(/name, fields/);
+ });
+
+ it('says the defaults are values, not a description of them', () => {
+ expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)(
+ { name: 'Piece' },
+ )).toThrow(/real values/);
+ });
+
+ it('refuses an empty or non-string name', () => {
+ expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)('', {}))
+ .toThrow(/takes the NAME first/);
+ expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)(42, {}))
+ .toThrow(/number 42/);
+ });
+
+ it('refuses a missing or non-object defaults, naming the component', () => {
+ expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)('Piece'))
+ .toThrow(/Component "Piece".*was given nothing/s);
+ });
+
+ it('still accepts the real call', () => {
+ const def = defineComponent('GuardOk', { speed: 100 });
+ expect(def._name).toBe('GuardOk');
+ expect(def._default).toEqual({ speed: 100 });
+ });
+});