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(editor): collision layer masks as a named-bit flags control

esenginebd9c144ebb1a
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.ts
index 14c86e681..53b1aee72 100644
--- a/desktop/electron/extractSchemas.ts
+++ b/desktop/electron/extractSchemas.ts
@@ -63,6 +63,7 @@ export interface ComponentSchema {
export interface SerializedFieldMeta {
enum?: Array<{ label: string; value: number }>;
flags?: Array<{ label: string; value: number }>;
+ bitmask?: { bits?: number; source?: string };
min?: number;
max?: number;
step?: number;
@@ -208,6 +209,7 @@ function pickFieldMeta(
const m: SerializedFieldMeta = {};
if (meta.enum && meta.enum.length) m.enum = meta.enum.map((o) => ({ ...o }));
if (meta.flags && meta.flags.length) m.flags = meta.flags.map((o) => ({ ...o }));
+ if (meta.bitmask) m.bitmask = { ...meta.bitmask };
if (meta.min != null) m.min = meta.min;
if (meta.max != null) m.max = meta.max;
if (meta.step != null) m.step = meta.step;
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 9d9715e4b..f382c7419 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -189,6 +189,7 @@ export interface UserComponentSchema {
export interface UserFieldMeta {
enum?: EnumOption[];
flags?: EnumOption[];
+ bitmask?: { bits?: number; source?: string };
min?: number;
max?: number;
step?: number;
@@ -264,6 +265,7 @@ export function fieldMetaFor(compType: string, key: string): UserFieldMeta | nul
return {
enum: fromDef.enum?.map((o) => ({ label: o.label, value: o.value })),
flags: fromDef.flags?.map((o) => ({ label: o.label, value: o.value })),
+ bitmask: fromDef.bitmask,
min: fromDef.min,
max: fromDef.max,
step: fromDef.step,
@@ -282,6 +284,23 @@ export function enumFieldOptions(compType: string, key: string): EnumOption[] |
return e && e.length ? e.map((o) => ({ ...o })) : null;
}
+// Editor-registered bit-label providers for bitmask fields (e.g. project collision
+// layers). The component def only marks a field a bitmask + names a source; the
+// labels are project-scoped, so the project layer injects them here.
+const bitmaskSources = new Map<string, () => EnumOption[]>();
+/** Register (or clear) a named source of bitmask bit labels. */
+export function setBitmaskSource(name: string, provider: (() => EnumOption[]) | null): void {
+ if (provider) bitmaskSources.set(name, provider);
+ else bitmaskSources.delete(name);
+}
+/** The bit options for a bitmask field: its source's labels, else `Layer N`. */
+function bitmaskOptions(meta: { bits?: number; source?: string }): EnumOption[] {
+ const src = meta.source ? bitmaskSources.get(meta.source) : undefined;
+ if (src) return src();
+ const bits = meta.bits ?? 32;
+ return Array.from({ length: bits }, (_, i) => ({ label: `Layer ${i}`, value: 1 << i }));
+}
+
/**
* Build one inspector field: an **asset control** for asset-ref fields (carrying
* the `@uuid:` ref or 0 for none), else a value-shape-inferred control.
@@ -297,6 +316,8 @@ function fieldFor(
let field: InspectorField | null;
if (at) {
field = { key, label: prettyLabel(key), type: 'asset', value: typeof value === 'string' ? value : 0, assetType: at };
+ } else if (meta?.bitmask) {
+ field = { key, label: prettyLabel(key), type: 'flags', value: Number(value) || 0, options: bitmaskOptions(meta.bitmask) };
} else if (meta?.flags && meta.flags.length) {
field = { key, label: prettyLabel(key), type: 'flags', value: Number(value) || 0, options: meta.flags.map((o) => ({ ...o })) };
} else if (meta?.enum && meta.enum.length) {
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 473b07580..7d9c40ba7 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -325,8 +325,15 @@ function FlagsControl({
const pop = usePopover();
const trigger = useRef<HTMLButtonElement>(null);
const bits = options.filter((o) => o.value !== 0);
+ const all = bits.reduce((m, o) => m | o.value, 0);
const active = bits.filter((o) => (value & o.value) === o.value);
- const summary = mixed ? '—' : active.length ? active.map((o) => prettyLabel(o.label)).join(' | ') : 'None';
+ const summary = mixed
+ ? '—'
+ : active.length === 0
+ ? 'None'
+ : active.length === bits.length && bits.length >= 4
+ ? 'Everything'
+ : active.map((o) => prettyLabel(o.label)).join(' | ');
const close = () => {
pop.close();
onEnd?.();
@@ -343,7 +350,17 @@ function FlagsControl({
<ChevronDown size={12} strokeWidth={2} />
</button>
{pop.anchor && (
- <Popover anchor={pop.anchor} width={Math.max(pop.anchor.width, 150)} onClose={close}>
+ <Popover anchor={pop.anchor} width={Math.max(pop.anchor.width, 160)} onClose={close}>
+ {bits.length >= 6 && (
+ <div className="dd-allnone">
+ <button type="button" onClick={() => onChange(all)}>
+ Everything
+ </button>
+ <button type="button" onClick={() => onChange(0)}>
+ Nothing
+ </button>
+ </div>
+ )}
<div className="dd-list">
{bits.map((o) => {
const on = !mixed && (value & o.value) === o.value;
diff --git a/desktop/src/theme/inspector.css b/desktop/src/theme/inspector.css
index 4e3dc1df9..9d5414ad1 100644
--- a/desktop/src/theme/inspector.css
+++ b/desktop/src/theme/inspector.css
@@ -161,6 +161,9 @@
.dd-opt .fchk { width: 13px; height: 13px; border: 1px solid var(--border-line); border-radius: var(--r-xs); display: grid; place-items: center; color: transparent; flex-shrink: 0; }
.dd-opt .fchk.on { background: var(--acc); border-color: var(--acc); color: #fff; }
.dd-empty { padding: 9px; text-align: center; color: var(--text-mute); font-size: var(--fs-xs); }
+.dd-allnone { display: flex; gap: 4px; padding: 2px 3px 5px; border-bottom: 1px solid var(--border); margin-bottom: 3px; }
+.dd-allnone button { flex: 1; height: 22px; background: var(--srf-4); border: 1px solid var(--border-line); border-radius: var(--r-xs); color: var(--text-dim); font-size: var(--fs-2xs); cursor: pointer; }
+.dd-allnone button:hover { background: var(--srf-5); color: var(--text); }
/* asset picker — a thumbnail grid in the popover */
.asset-grid { overflow-y: auto; display: grid; grid-template-columns: repeat(3, 1fr); gap: 3px; padding: 2px; min-height: 0; max-height: 280px; }
diff --git a/desktop/tests/inspector-model.test.ts b/desktop/tests/inspector-model.test.ts
index 7ce88e460..675d88f74 100644
--- a/desktop/tests/inspector-model.test.ts
+++ b/desktop/tests/inspector-model.test.ts
@@ -14,7 +14,7 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import type { SceneData } from 'esengine';
import { EditorSession } from '@/engine/EditorSession';
-import { setUserSchemas, enumFieldOptions } from '@/engine/schema';
+import { setUserSchemas, enumFieldOptions, setBitmaskSource } from '@/engine/schema';
import { setPrefabBaseResolver } from '@/engine/SceneQuery';
/** A one-entity scene carrying a Camera with the given component-data overrides. */
@@ -292,6 +292,37 @@ describe('Unknown-component inspector (schemas.json consumer)', () => {
});
});
+describe('Bitmask fields (collision layers)', () => {
+ afterEach(() => setBitmaskSource('collisionLayers', null));
+ function colliderScene(categoryBits: number): SceneData {
+ return {
+ version: '1.0',
+ name: 'c',
+ entities: [{ id: 1, name: 'C', parent: null, children: [], components: [{ type: 'BoxCollider', data: { categoryBits } }] }],
+ } as unknown as SceneData;
+ }
+ const catBits = (S: EditorSession) =>
+ S.query.readInspector(1).find((c) => c.name === 'BoxCollider')!.fields.find((f) => f.key === 'categoryBits')!;
+
+ it('renders a collision bitmask as 16 named-bit flags (default Layer N)', () => {
+ const S = EditorSession.create();
+ S.model.adopt(colliderScene(5), new Map([[1, 1]])); // bits 0 and 2
+ const cb = catBits(S);
+ expect(cb.type).toBe('flags');
+ expect(cb.value).toBe(5);
+ expect(cb.options!.length).toBe(16);
+ expect(cb.options![0]).toEqual({ label: 'Layer 0', value: 1 });
+ expect(cb.options![2]).toEqual({ label: 'Layer 2', value: 4 });
+ });
+
+ it('a registered source supplies the bit labels (named layers)', () => {
+ setBitmaskSource('collisionLayers', () => [{ label: 'Player', value: 1 }, { label: 'Enemy', value: 2 }]);
+ const S = EditorSession.create();
+ S.model.adopt(colliderScene(1), new Map([[1, 1]]));
+ expect(catBits(S).options!.map((o) => o.label)).toEqual(['Player', 'Enemy']);
+ });
+});
+
describe('Multi-selection inspector (D6)', () => {
function scene2(): SceneData {
return {
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 6fad16e51..f5f5a7d3e 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -36,6 +36,12 @@ export interface FieldMeta {
enum?: ReadonlyArray<{ label: string; value: number }>;
/** Render as a bitmask multi-select; each option is a single bit. */
flags?: ReadonlyArray<{ label: string; value: number }>;
+ /**
+ * Render as a bitmask whose bit LABELS are resolved by the editor (e.g. named
+ * collision layers from project settings) rather than fixed here. `bits` is the
+ * count (default 32); `source` names the editor's label provider.
+ */
+ bitmask?: { bits?: number; source?: string };
/** Hard numeric range — clamps both typed entry and drag-scrub. */
min?: number;
max?: number;
diff --git a/sdk/src/physics/PhysicsComponents.ts b/sdk/src/physics/PhysicsComponents.ts
index 2d6748253..8d0513a75 100644
--- a/sdk/src/physics/PhysicsComponents.ts
+++ b/sdk/src/physics/PhysicsComponents.ts
@@ -8,6 +8,14 @@
import type { Vec2 } from '../types';
import { defineBuiltin, defineComponent, enumOptions } from '../component';
+// Box2D collision filtering: a body's own layers (category) and the layers it
+// collides with (mask), as named bitmasks. Bit labels come from the project's
+// collision-layer settings (the `collisionLayers` source) — see the editor.
+const COLLISION_FILTER_META = {
+ categoryBits: { bitmask: { bits: 16, source: 'collisionLayers' }, advanced: true },
+ maskBits: { bitmask: { bits: 16, source: 'collisionLayers' }, advanced: true },
+} as const;
+
// =============================================================================
// Component Data Interfaces
// =============================================================================
@@ -139,7 +147,7 @@ export const BoxCollider = defineBuiltin<BoxColliderData>('BoxCollider', {
enabled: true,
categoryBits: 0x0001,
maskBits: 0xFFFF,
-});
+}, { fields: { ...COLLISION_FILTER_META } });
export const CircleCollider = defineBuiltin<CircleColliderData>('CircleCollider', {
radius: 0.5,
@@ -151,7 +159,7 @@ export const CircleCollider = defineBuiltin<CircleColliderData>('CircleCollider'
enabled: true,
categoryBits: 0x0001,
maskBits: 0xFFFF,
-});
+}, { fields: { ...COLLISION_FILTER_META } });
export const CapsuleCollider = defineBuiltin<CapsuleColliderData>('CapsuleCollider', {
radius: 0.25,
@@ -164,7 +172,7 @@ export const CapsuleCollider = defineBuiltin<CapsuleColliderData>('CapsuleCollid
enabled: true,
categoryBits: 0x0001,
maskBits: 0xFFFF,
-});
+}, { fields: { ...COLLISION_FILTER_META } });
export const SegmentCollider = defineBuiltin<SegmentColliderData>('SegmentCollider', {
point1: { x: -0.5, y: 0 },
@@ -176,7 +184,7 @@ export const SegmentCollider = defineBuiltin<SegmentColliderData>('SegmentCollid
enabled: true,
categoryBits: 0x0001,
maskBits: 0xFFFF,
-});
+}, { fields: { ...COLLISION_FILTER_META } });
export const PolygonCollider = defineComponent<PolygonColliderData>('PolygonCollider', {
vertices: [
@@ -193,7 +201,7 @@ export const PolygonCollider = defineComponent<PolygonColliderData>('PolygonColl
enabled: true,
categoryBits: 0x0001,
maskBits: 0xFFFF,
-});
+}, { fields: { ...COLLISION_FILTER_META } });
export const ChainCollider = defineComponent<ChainColliderData>('ChainCollider', {
points: [
@@ -208,7 +216,7 @@ export const ChainCollider = defineComponent<ChainColliderData>('ChainCollider',
categoryBits: 0x0001,
maskBits: 0xFFFF,
enabled: true,
-});
+}, { fields: { ...COLLISION_FILTER_META } });
// =============================================================================
// Joint Components