Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(physics): collision layer matrix in Project Settings

esenginee76f2d71979d
diff --git a/desktop/src/components/SettingsDialog.tsx b/desktop/src/components/SettingsDialog.tsx
index e01bdf8ff..fd26b4ef2 100644
--- a/desktop/src/components/SettingsDialog.tsx
+++ b/desktop/src/components/SettingsDialog.tsx
@@ -16,7 +16,7 @@ import { useEditorStore } from '@/store/editorStore';
import { useSettings } from '@/store/settingsStore';
import { settingsRegistry } from '@/settings/registry';
import { eventToChord, formatKeybinding } from '@/commands/keybinding';
-import type { Setting, NumberSetting, KeybindingSetting, StringListSetting } from '@/settings/types';
+import type { Setting, NumberSetting, KeybindingSetting, StringListSetting, MatrixSetting } from '@/settings/types';
// A bound list setting's getter returns a fresh array each call; useShallow below
// keeps the read referentially stable (else useSyncExternalStore loops). A shared
@@ -147,6 +147,48 @@ function StringListControl({ setting }: { setting: StringListSetting }) {
);
}
+const EMPTY_MASKS: readonly number[] = [];
+
+function MatrixControl({ setting }: { setting: MatrixSetting }) {
+ const setValue = useSettings((s) => s.setValue);
+ const value = useSettings(useShallow((s) => s.getValue<number[]>(setting.id) ?? (EMPTY_MASKS as number[])));
+ const labels = setting.labels();
+ const masks = Array.from({ length: setting.count }, (_, i) => value[i] ?? 0xffff);
+ // Show layer 0 (Default) + any named layer — the matrix stays readable.
+ const shown = Array.from({ length: setting.count }, (_, i) => i).filter((i) => i === 0 || (labels[i] ?? '') !== '');
+ const collides = (i: number, j: number) => ((masks[i] >> j) & 1) === 1;
+ const toggle = (i: number, j: number) => {
+ const on = !collides(i, j);
+ const setBit = (m: number, b: number) => (on ? m | (1 << b) : m & ~(1 << b)) & 0xffff;
+ const next = masks.slice();
+ next[i] = setBit(next[i], j);
+ next[j] = setBit(next[j], i); // keep the matrix symmetric
+ setValue(setting.id, next);
+ };
+ return (
+ <table className="set-matrix">
+ <thead>
+ <tr>
+ <th />
+ {shown.map((j) => <th key={j} className="set-matrix-col"><span>{labels[j] || `Layer ${j}`}</span></th>)}
+ </tr>
+ </thead>
+ <tbody>
+ {shown.map((i) => (
+ <tr key={i}>
+ <th className="set-matrix-row">{labels[i] || `Layer ${i}`}</th>
+ {shown.map((j) => (
+ <td key={j}>
+ <input type="checkbox" checked={collides(i, j)} onChange={() => toggle(i, j)} />
+ </td>
+ ))}
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ );
+}
+
function Control({ setting }: { setting: Setting }) {
const setValue = useSettings((s) => s.setValue);
// useShallow: a bound list setting returns a fresh array each read, which would
@@ -217,6 +259,8 @@ function Control({ setting }: { setting: Setting }) {
);
case 'stringList':
return <StringListControl setting={setting} />;
+ case 'matrix':
+ return <MatrixControl setting={setting} />;
}
}
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 20c48cdb7..ab121c23e 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -526,7 +526,6 @@ class ProjectStoreImpl {
// Project Settings. The collision matrix is sent ONLY when configured — otherwise
// a layer's mask would override each collider's own maskBits (the two are exclusive).
const f = this.physicsFeature();
- const raw = this.state?.features?.physics;
const physicsConfig: PhysicsPluginConfig = {
gravity: f.gravity,
fixedTimestep: f.fixedTimestep,
@@ -537,7 +536,11 @@ class ProjectStoreImpl {
enableSleep: f.enableSleep,
enableContinuous: f.enableContinuous,
};
- if (raw?.collisionLayerMasks) physicsConfig.collisionLayerMasks = f.collisionLayerMasks;
+ // Send the collision matrix ONLY when it actually restricts a pair — an all-collide
+ // matrix would otherwise override each single-layer collider's own maskBits for nothing.
+ if (f.collisionLayerMasks.some((m) => (m & 0xffff) !== 0xffff)) {
+ physicsConfig.collisionLayerMasks = f.collisionLayerMasks;
+ }
return { sceneData, assetManifest, physicsEnabled: f.enabled, physicsConfig };
}
diff --git a/desktop/src/settings/projectSettings.ts b/desktop/src/settings/projectSettings.ts
index 9c8388548..1ec2e0938 100644
--- a/desktop/src/settings/projectSettings.ts
+++ b/desktop/src/settings/projectSettings.ts
@@ -80,6 +80,23 @@ settingsRegistry.register({
},
});
+settingsRegistry.register({
+ id: 'project.physics.collisionMatrix',
+ type: 'matrix',
+ scope: 'project',
+ section: 'physics',
+ group: 'Collision Layers',
+ label: 'Collision matrix',
+ description: 'Which layers collide. A collider on a single named layer derives its mask from this row (so it overrides the collider’s own Mask). All-on = no restriction.',
+ count: 16,
+ labels: () => ProjectStore.physicsFeature().collisionLayers,
+ default: Array.from({ length: 16 }, () => 0xffff),
+ bind: {
+ get: () => ProjectStore.physicsFeature().collisionLayerMasks,
+ set: (v) => void ProjectStore.setPhysics({ collisionLayerMasks: v }),
+ },
+});
+
// ── Packaging (per-platform Project Settings; read by the export, persisted to project.esproject) ──
settingsRegistry.registerSection({ id: 'packaging', label: 'Packaging', category: 'project', order: 3 });
diff --git a/desktop/src/settings/types.ts b/desktop/src/settings/types.ts
index e529e08f5..44def603f 100644
--- a/desktop/src/settings/types.ts
+++ b/desktop/src/settings/types.ts
@@ -91,6 +91,18 @@ export interface StringListSetting extends BaseSetting<string[]> {
placeholder?: (i: number) => string;
}
+/**
+ * A symmetric NxN boolean matrix stored as `count` row bitmasks — the collision
+ * matrix (which layer collides with which). value[i] bit j set ⇒ row i ↔ col j on.
+ * Only rows whose {@link labels} entry is non-empty (plus row 0) are shown.
+ */
+export interface MatrixSetting extends BaseSetting<number[]> {
+ type: 'matrix';
+ count: number;
+ /** Row/column labels (e.g. the named collision layers), read at render time. */
+ labels: () => string[];
+}
+
export type Setting =
| BooleanSetting
| NumberSetting
@@ -98,6 +110,7 @@ export type Setting =
| StringSetting
| ColorSetting
| KeybindingSetting
- | StringListSetting;
+ | StringListSetting
+ | MatrixSetting;
-export type SettingValue = boolean | number | string | string[];
+export type SettingValue = boolean | number | string | string[] | number[];
diff --git a/desktop/src/theme/settings.css b/desktop/src/theme/settings.css
index 6110d2068..818d46ff7 100644
--- a/desktop/src/theme/settings.css
+++ b/desktop/src/theme/settings.css
@@ -153,6 +153,15 @@
.set-list-item { height: 24px; min-width: 0; background: var(--inset); border: 1px solid var(--border); border-radius: var(--r-sm); padding: 0 7px; color: var(--text); font-size: var(--fs-xs); outline: none; }
.set-list-item:focus { border-color: var(--acc); box-shadow: 0 0 0 2px var(--acc-soft); }
.set-list-item::placeholder { color: var(--text-mute); }
+
+/* Collision matrix (which layer collides with which) */
+.set-matrix { border-collapse: collapse; font-size: var(--fs-xs); color: var(--text-dim); }
+.set-matrix th { font-weight: 400; color: var(--text-dim); padding: 2px 4px; }
+.set-matrix th.set-matrix-row { text-align: right; white-space: nowrap; }
+.set-matrix th.set-matrix-col { height: 64px; vertical-align: bottom; }
+.set-matrix th.set-matrix-col span { display: inline-block; writing-mode: vertical-rl; transform: rotate(180deg); white-space: nowrap; }
+.set-matrix td { text-align: center; padding: 1px 4px; }
+.set-matrix input[type='checkbox'] { cursor: pointer; }
.set-str { width: 200px; height: 24px; background: var(--inset); border: 1px solid var(--border); border-radius: var(--r-sm); padding: 0 7px; color: var(--text); font-size: var(--fs-xs); font-family: var(--mono); outline: none; }
.set-str:focus { border-color: var(--acc); box-shadow: 0 0 0 2px var(--acc-soft); }
.set-str::placeholder { color: var(--text-mute); font-family: var(--sans, inherit); }