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
feat(editor): collision layer masks as a named-bit flags control
esenginebd9c144ebb1a
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.tsindex 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.tsindex 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 | nulreturn {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.tsxindex 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.cssindex 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.tsindex 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.tsindex 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.tsindex 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>('CapsuleCollidenabled: 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>('SegmentCollidenabled: 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>('PolygonCollenabled: 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