A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(editor): a settings list survives having something in it
esengined49d8bdab0c8
diff --git a/desktop/src/components/SettingsRow.tsx b/desktop/src/components/SettingsRow.tsxindex 549cd9104..17f10d8f9 100644--- a/desktop/src/components/SettingsRow.tsx+++ b/desktop/src/components/SettingsRow.tsx@@ -11,7 +11,7 @@* on that target's page. One renderer, so a row cannot look or behave like* two different things depending on which dialog you opened.*/-import { useEffect, useRef, useState, useSyncExternalStore } from 'react';+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';import type { PointerEvent as ReactPointerEvent } from 'react';import { useShallow } from 'zustand/react/shallow';import { RotateCcw, FolderSearch, Plus, Trash2, ChevronRight, Check, KeyRound, X } from 'lucide-react';@@ -24,7 +24,7 @@ import { Segmented } from '@/components/Segmented';import { Select } from '@/components/Select';import { ColorControl } from '@/components/ColorControl';import { refreshSecret, secretStatus, storeSecret, forgetSecret, subscribeSecrets } from '@/store/SecretStore';-import type { Setting, NumberSetting, KeybindingSetting, StringListSetting, PathSetting, SecretSetting, MatrixSetting, FlagListSetting, ObjectListSetting, ObjectListColumn } from '@/settings/types';+import type { Setting, BooleanSetting, EnumSetting, NumberSetting, StringSetting, ColorSetting, ColorPickerSetting, KeybindingSetting, StringListSetting, PathSetting, SecretSetting, MatrixSetting, FlagListSetting, ObjectListSetting, ObjectListColumn } from '@/settings/types';import { t } from '@/i18n';// A bound list setting's getter returns a fresh array each call; useShallow below@@ -186,6 +186,7 @@ function PathControl({ setting }: { setting: PathSetting }) {<inputclassName="set-str"value={value}+ title={value}placeholder={setting.placeholder ?? ''}spellCheck={false}onChange={(e) => setValue(setting.id, e.target.value)}@@ -366,7 +367,6 @@ function FlagListControl({ setting }: { setting: FlagListSetting }) {* every keystroke — the setting store is the working copy, and a row that is* momentarily invalid shows its complaint inline instead of being refused.*/-const EMPTY_ROWS: readonly Record<string, unknown>[] = [];/** Read `a.b.c` out of a row. */function readPath(row: Record<string, unknown>, path: string): unknown {@@ -510,21 +510,56 @@ function ObjectListField({*/function ObjectListControl({ setting }: { setting: ObjectListSetting }) {const setValue = useSettings((s) => s.setValue);- // useShallow, not a bare selector: `getValue` hands back a fresh array each- // call, and Object.is on a new reference re-renders forever — the same reason- // FlagListControl below reads its value this way.- const rows = useSettings(useShallow((s) => s.getValue<Record<string, unknown>[]>(setting.id) ?? (EMPTY_ROWS as Record<string, unknown>[])));+ /**+ * Read through the serialized form, the only stable snapshot here: a bound list+ * hands back fresh row OBJECTS, which a shallow compare never calls equal, so+ * every read is a change and the tree re-renders until React kills it (#185).+ * An empty list compares equal, which is why this can look fine for years.+ */+ const serialized = useSettings((s) => JSON.stringify(s.getValue<Record<string, unknown>[]>(setting.id) ?? []));+ const rows = useMemo(() => JSON.parse(serialized) as Record<string, unknown>[], [serialized]);+ /**+ * Rows being typed, which the store has not been given yet. A row starts BLANK+ * and a store may normalize a blank row away (an achievement id nothing could+ * match), so writing it through makes Add a no-op. `rowError` already says+ * which rows are real; a row waits here until it is one.+ */+ const [draft, setDraft] = useState<Record<string, unknown>[]>([]);const [expanded, setExpanded] = useState<ReadonlySet<number>>(() => new Set());const cols = setting.columns;const details = setting.detailColumns ?? [];const grid = { gridTemplateColumns: `${cols.map((c) => c.width ?? '1fr').join(' ')}${details.length > 0 ? ' 24px' : ''} 24px` };+ const all = draft.length > 0 ? [...rows, ...draft] : rows;+ const errorOf = (row: Record<string, unknown>, within: Record<string, unknown>[]) =>+ setting.rowError?.(row, within) ?? null;// Read the CURRENT rows rather than the render's closure: editing two fields// in quick succession would otherwise have the second patch built from the// pre-first snapshot and silently drop the first edit.const patch = (i: number, key: string, v: unknown) => {const live = useSettings.getState().getValue<Record<string, unknown>[]>(setting.id) ?? rows;- setValue(setting.id, live.map((r, j) => (j === i ? writePath(r, key, v) : r)));+ if (i < live.length) {+ setValue(setting.id, live.map((r, j) => (j === i ? writePath(r, key, v) : r)));+ return;+ }+ const edited = draft.map((r, j) => (j === i - live.length ? writePath(r, key, v) : r));+ const merged = [...live, ...edited];+ const ready = edited.filter((r) => !errorOf(r, merged));+ if (ready.length > 0) setValue(setting.id, [...live, ...ready]);+ setDraft(edited.filter((r) => errorOf(r, merged)));+ };+ const remove = (i: number, row: Record<string, unknown>) => {+ if (i < rows.length) setValue(setting.id, rows.filter((_, j) => j !== i));+ else setDraft(draft.filter((_, j) => j !== i - rows.length));+ setting.onRowRemoved?.(row);+ setExpanded(new Set());+ };+ // A new row joins the store directly when it is already valid there; only one+ // that is not yet a row waits in the draft.+ const add = () => {+ const row = setting.newRow();+ if (errorOf(row, [...rows, row])) setDraft([...draft, row]);+ else setValue(setting.id, [...rows, row]);};const toggle = (i: number) => setExpanded((prev) => {const next = new Set(prev);@@ -534,16 +569,16 @@ function ObjectListControl({ setting }: { setting: ObjectListSetting }) {return (<div className="set-objlist">- {rows.length === 0 && setting.emptyHint && <div className="set-objlist-empty">{setting.emptyHint}</div>}- {rows.length > 0 && (+ {all.length === 0 && setting.emptyHint && <div className="set-objlist-empty">{setting.emptyHint}</div>}+ {all.length > 0 && (<div className="set-objlist-head" style={grid}>{cols.map((c) => <span key={c.key}>{c.label}</span>)}{details.length > 0 && <span />}<span /></div>)}- {rows.map((row, i) => {- const err = setting.rowError?.(row, rows) ?? null;+ {all.map((row, i) => {+ const err = errorOf(row, all);const open = expanded.has(i);return (<div key={i} className={`set-objlist-row${err ? ' invalid' : ''}`}>@@ -566,11 +601,7 @@ function ObjectListControl({ setting }: { setting: ObjectListSetting }) {type="button"className="set-objlist-del"title={t('set.objList.remove')}- onClick={() => {- setValue(setting.id, rows.filter((_, j) => j !== i));- setting.onRowRemoved?.(row);- setExpanded(new Set());- }}+ onClick={() => remove(i, row)}><Trash2 size={12} strokeWidth={2} /></button>@@ -593,7 +624,7 @@ function ObjectListControl({ setting }: { setting: ObjectListSetting }) {<buttontype="button"className="set-objlist-add"- onClick={() => setValue(setting.id, [...rows, setting.newRow()])}+ onClick={add}><Plus size={12} strokeWidth={2.2} /> {setting.addLabel}</button>@@ -601,89 +632,105 @@ function ObjectListControl({ setting }: { setting: ObjectListSetting }) {);}-function Control({ setting }: { setting: Setting }) {+/**+ * A scalar control reads its OWN value, like every delegated control below.+ * Reading one value for ALL types subscribes a row to a shape it does not+ * render, and for a list of rows that snapshot is never equal to itself — an+ * unbounded re-render (#185) driven by a control that is not even on screen.+ */+function BooleanControl({ setting }: { setting: BooleanSetting }) {const setValue = useSettings((s) => s.setValue);- // useShallow: a bound list setting returns a fresh array each read, which would- // otherwise make this snapshot change every render and loop.- const value = useSettings(useShallow((s) => s.getValue(setting.id)));- switch (setting.type) {- case 'boolean':- return (+ const on = useSettings((s) => Boolean(s.getValue(setting.id)));+ return (+ <span+ className={`toggle${on ? ' on' : ''}`}+ role="switch"+ aria-checked={on}+ tabIndex={0}+ onClick={() => setValue(setting.id, !on)}+ onKeyDown={(e) => {+ if (e.key === ' ' || e.key === 'Enter') {+ e.preventDefault();+ setValue(setting.id, !on);+ }+ }}+ />+ );+}++function EnumControl({ setting }: { setting: EnumSetting }) {+ const setValue = useSettings((s) => s.setValue);+ const value = String(useSettings((s) => s.getValue(setting.id)));+ const options = setting.options.map((o) => ({ value: o.value, label: o.label }));+ return setting.segmented ? (+ <Segmented value={value} onChange={(v) => setValue(setting.id, v)} ariaLabel={setting.label} options={options} />+ ) : (+ <Select ariaLabel={setting.label} value={value} options={options} onChange={(v) => setValue(setting.id, v)} />+ );+}++function SwatchControl({ setting }: { setting: ColorSetting }) {+ const setValue = useSettings((s) => s.setValue);+ const value = String(useSettings((s) => s.getValue(setting.id) ?? ''));+ return (+ <div className="set-swatches">+ {setting.swatches.map((c) => (<span- className={`toggle${value ? ' on' : ''}`}- role="switch"- aria-checked={Boolean(value)}- tabIndex={0}- onClick={() => setValue(setting.id, !value)}- onKeyDown={(e) => {- if (e.key === ' ' || e.key === 'Enter') {- e.preventDefault();- setValue(setting.id, !value);- }- }}+ key={c}+ className={`set-swatch${value === c ? ' on' : ''}`}+ style={{ background: c }}+ title={c}+ onClick={() => setValue(setting.id, c)}/>- );- case 'enum': {- const options = setting.options.map((o) => ({ value: o.value, label: o.label }));- if (setting.segmented) {- return (- <Segmented- value={String(value)}- onChange={(v) => setValue(setting.id, v)}- ariaLabel={setting.label}- options={options}- />- );- }- return (- <Select- ariaLabel={setting.label}- value={String(value)}- options={options}- onChange={(v) => setValue(setting.id, v)}- />- );- }+ ))}+ </div>+ );+}++function ColorPickerControl({ setting }: { setting: ColorPickerSetting }) {+ const setValue = useSettings((s) => s.setValue);+ const hex = String(useSettings((s) => s.getValue(setting.id)) ?? '');+ return (+ <div className={`set-colorpicker${hex ? '' : ' inherited'}`}>+ <ColorControl+ value={hex || setting.placeholderColor?.() || '#00000000'}+ onChange={(v) => setValue(setting.id, v)}+ />+ {!hex && <span className="set-inherit">{t('set.inherited')}</span>}+ </div>+ );+}++function StringControl({ setting }: { setting: StringSetting }) {+ const setValue = useSettings((s) => s.setValue);+ const value = String(useSettings((s) => s.getValue(setting.id)) ?? '');+ return (+ <input+ className="set-str"+ value={value}+ placeholder={setting.placeholder ?? ''}+ spellCheck={false}+ onChange={(e) => setValue(setting.id, e.target.value)}+ />+ );+}++function Control({ setting }: { setting: Setting }) {+ switch (setting.type) {+ case 'boolean':+ return <BooleanControl setting={setting} />;+ case 'enum':+ return <EnumControl setting={setting} />;case 'number':return <NumberControl setting={setting} />;case 'color':- return (- <div className="set-swatches">- {setting.swatches.map((c) => (- <span- key={c}- className={`set-swatch${value === c ? ' on' : ''}`}- style={{ background: c }}- title={c}- onClick={() => setValue(setting.id, c)}- />- ))}- </div>- );- case 'colorpicker': {- const hex = String(value ?? '');- return (- <div className={`set-colorpicker${hex ? '' : ' inherited'}`}>- <ColorControl- value={hex || setting.placeholderColor?.() || '#00000000'}- onChange={(v) => setValue(setting.id, v)}- />- {!hex && <span className="set-inherit">{t('set.inherited')}</span>}- </div>- );- }+ return <SwatchControl setting={setting} />;+ case 'colorpicker':+ return <ColorPickerControl setting={setting} />;case 'keybinding':return <KeybindCapture setting={setting} />;case 'string':- return (- <input- className="set-str"- value={String(value ?? '')}- placeholder={setting.placeholder ?? ''}- spellCheck={false}- onChange={(e) => setValue(setting.id, e.target.value)}- />- );+ return <StringControl setting={setting} />;case 'path':return <PathControl setting={setting} />;case 'secret':diff --git a/desktop/src/theme/settings.css b/desktop/src/theme/settings.cssindex fe3fe20e9..9d3d4e93a 100644--- a/desktop/src/theme/settings.css+++ b/desktop/src/theme/settings.css@@ -201,8 +201,11 @@/* A path row is wider than a plain string: an absolute program path is long, andtruncating the interesting end of it (the executable's name) is what makes theCocos-style field hard to read at a glance. */-.set-path { display: flex; align-items: center; gap: 4px; }-.set-path .set-str { width: 300px; }+/* Fills the control column rather than stating a width: a path is longer than any+ column worth reserving, and a fixed one overflowed LEFT, over the label. The+ full value is the input's own title. */+.set-path { display: flex; align-items: center; gap: 4px; flex: 1; min-width: 0; }+.set-path .set-str { flex: 1; min-width: 0; }/* A credential: an entry field until one is held, then a statement that one is.Uncolored on purpose — "configured" is a fact, not a warning or a success. */.set-secret { display: flex; align-items: center; justify-content: flex-end; gap: 4px; width: 100%; }diff --git a/desktop/tests/packaging-settings-home.test.ts b/desktop/tests/packaging-settings-home.test.tsindex b9d432af6..1af96360e 100644--- a/desktop/tests/packaging-settings-home.test.ts+++ b/desktop/tests/packaging-settings-home.test.ts@@ -15,6 +15,7 @@ import { settingsRegistry } from '@/settings/registry';import { ProjectStore } from '@/project/ProjectStore';import { BUILTIN_PLATFORMS } from '@/project/platforms';import { platformLabel, unlabeledBuiltins } from '@/project/platformLabels';+import type { ObjectListSetting } from '@/settings/types';/** Every registered setting that claims a packaging target. */const targetOwned = () => settingsRegistry.all().filter((s) => s.platform);@@ -84,6 +85,37 @@ describe('a packaging setting has one home', () => {});});+describe('a list whose store normalizes rows away', () => {+ const real = { get: ProjectStore.packagingSettings, set: ProjectStore.setPackaging };+ afterEach(() => {+ ProjectStore.packagingSettings = real.get;+ ProjectStore.setPackaging = real.set;+ });++ it('flags a blank new row, because writing it through loses it', () => {+ // The store drops an id no achievement could match, so a blank row written+ // straight through never comes back and Add looks dead. Holding a row that+ // `rowError` rejects is the rule that pairs with it.+ const s = settingsRegistry.get('project.packaging.achievements') as ObjectListSetting;+ let stored: string[] = [];+ ProjectStore.packagingSettings = () => ({ achievements: stored });+ ProjectStore.setPackaging = (async (p: { achievements?: string[] }) => {+ stored = p.achievements ?? stored;+ }) as typeof ProjectStore.setPackaging;++ const row = s.newRow();+ s.bind!.set([...s.bind!.get(), row]);+ expect(s.bind!.get()).toHaveLength(0);+ expect(s.rowError!(row, [row])).toBeTruthy();++ // Once named it survives the same round trip.+ const named = { id: 'FIRST_BLOOD' };+ expect(s.rowError!(named, [named])).toBeNull();+ s.bind!.set([named]);+ expect(s.bind!.get()).toEqual([{ id: 'FIRST_BLOOD' }]);+ });+});+describe('rows that only apply on one answer', () => {const visible = (id: string) => settingsRegistry.get(id)!.visibleWhen?.() !== false;// The predicates read the live project, so the packaging accessor is stood indiff --git a/desktop/tests/settings-snapshot.test.ts b/desktop/tests/settings-snapshot.test.tsnew file mode 100644index 000000000..ab106b036--- /dev/null+++ b/desktop/tests/settings-snapshot.test.ts@@ -0,0 +1,82 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file What a settings row is allowed to subscribe to.+ *+ * Every zustand selector is a useSyncExternalStore snapshot, so it must+ * not change between two reads of an unchanged value. A getter handing+ * back fresh OBJECTS never compares equal under a shallow check, and the+ * row re-renders until React tears the whole tree down (#185) — which is+ * what a non-empty objectList did, invisibly, while every such list in+ * the editor happened to be empty.+ */+import { readFileSync } from 'node:fs';+import { describe, it, expect, afterEach } from 'vitest';+import '@/settings';+import { settingsRegistry } from '@/settings/registry';+import { useSettings } from '@/store/settingsStore';+import { ProjectStore } from '@/project/ProjectStore';++const read = (id: string) => useSettings.getState().getValue(id);+const shallowEqual = (a: unknown, b: unknown): boolean => {+ if (!Array.isArray(a) || !Array.isArray(b)) return Object.is(a, b);+ return a.length === b.length && a.every((x, i) => Object.is(x, b[i]));+};++describe('every registered setting', () => {+ const real = { packaging: ProjectStore.packagingSettings, presets: ProjectStore.screenPresets };+ afterEach(() => {+ ProjectStore.packagingSettings = real.packaging;+ ProjectStore.screenPresets = real.presets;+ });++ it('reads a snapshot that is stable across two calls', () => {+ // The project-bound lists are stood up NON-EMPTY, or this passes on `[]`+ // comparing equal to itself and says nothing about the case that broke.+ ProjectStore.packagingSettings = () => ({ achievements: ['FIRST_BLOOD'] });+ ProjectStore.screenPresets = () => ([{ id: 'phone', label: 'Phone', width: 1080, height: 1920 }]);+ for (const id of ['project.packaging.achievements', 'project.display.screenPresets']) {+ expect((read(id) as unknown[]).length).toBeGreaterThan(0);+ }+ for (const s of settingsRegistry.all()) {+ const a = read(s.id);+ const b = read(s.id);+ // Rows of objects are exempt and read through their serialized form+ // instead — see the objectList control. Everything else has to be stable+ // as-is, because that is what its control subscribes to.+ if (s.type === 'objectList') expect(JSON.stringify(b)).toBe(JSON.stringify(a));+ else expect(shallowEqual(a, b)).toBe(true);+ }+ });+});++describe('a non-empty list of rows', () => {+ const real = ProjectStore.packagingSettings;+ afterEach(() => { ProjectStore.packagingSettings = real; });++ it('is not shallow-stable, which is why it is not read that way', () => {+ // The pairing that matters: were this list read with a shallow comparison —+ // as every other list setting is — it would report a change on every render+ // forever. The serialized read is what makes it a usable snapshot.+ ProjectStore.packagingSettings = () => ({ achievements: ['FIRST_BLOOD'] });+ const id = 'project.packaging.achievements';+ expect(read(id)).toEqual([{ id: 'FIRST_BLOOD' }]);+ expect(shallowEqual(read(id), read(id))).toBe(false);+ expect(JSON.stringify(read(id))).toBe(JSON.stringify(read(id)));+ });++ it('is read by a control that does not compare it shallowly', () => {+ // No node test can render the rule, so it is checked where it is written.+ // Both halves count: the row control must not read shallowly, and Control+ // must not take a read on behalf of every type.+ const src = readFileSync(new URL('../src/components/SettingsRow.tsx', import.meta.url), 'utf8');+ const body = (name: string) => {+ const from = src.indexOf(`function ${name}(`);+ expect(from).toBeGreaterThan(-1);+ return src.slice(from, src.indexOf('\n}\n', from));+ };+ expect(body('ObjectListControl')).not.toContain('useSettings(useShallow');+ expect(body('ObjectListControl')).toContain('JSON.stringify');+ expect(body('Control')).not.toContain('useSettings(');+ });+});