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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file ui/behavior/toggle.ts
* @brief UIToggle — data-driven on/off state.
*
* A group makes them exclusive: UIToggleGroup on a common ancestor.
*
* The component IS the state (`isOn` + the check-indicator entity ref); the
* system flips it on click and is the single writer of the check visual. Any
* writer — the pointer, `setValue`, a binding, the editor inspector — shows
* the indicator and fires `change` identically, so a prefab-placed toggle
* works without code.
*/
import { defineComponent } from '../../ecs/component';
import { defineSystem, type SystemDef } from '../../ecs/system';
import type { World } from '../../ecs/world';
import type { Entity } from '../../types';
import { setUIVisible } from '../core/compose';
import { Interactable, type InteractableData } from '../input/interactable';
import { UIEventType, type UIEventQueue } from '../core/events';
import { EntityStateMap, walkParentChain } from '../util/helpers';
export interface UIToggleData {
isOn: boolean;
/** The on-state indicator entity (UIVisual.enabled tracks `isOn`). */
check: Entity;
}
export const UIToggle = defineComponent<UIToggleData>('UIToggle', {
isOn: false,
check: 0 as Entity,
}, { entityFields: ['check'] });
export interface UIToggleGroupData {
/** Whether the group may end up with nothing selected. */
allowSwitchOff: boolean;
}
/**
* Makes the UIToggles beneath it exclusive — a radio group, a tab bar, a
* difficulty picker. Sits on the COMMON ANCESTOR, like FlexContainer, so the
* toggles need no reference to each other or to it.
*/
export const UIToggleGroup = defineComponent<UIToggleGroupData>('UIToggleGroup', {
allowSwitchOff: false,
}, {
fields: {
allowSwitchOff: { tooltip: 'Let a click turn the selected toggle off, leaving none selected.' },
},
});
/** The nearest ancestor that groups this toggle, or 0 when it is on its own. */
function groupOf(world: World, entity: Entity): Entity {
let group = 0 as Entity;
walkParentChain(world, entity, (ancestor) => {
if (!world.has(ancestor, UIToggleGroup)) return false;
group = ancestor;
return true;
});
return group;
}
/** Turn off every other toggle the same group owns. */
function clearSiblings(world: World, group: Entity, keep: Entity): void {
for (const other of world.getEntitiesWithComponents([UIToggle])) {
if (other === keep) continue;
const d = world.get(other, UIToggle) as UIToggleData;
if (!d.isOn || groupOf(world, other) !== group) continue;
d.isOn = false;
world.insert(other, UIToggle, d);
}
}
/** Flips on click; syncs `isOn` → check visibility; emits `change`. */
export function createToggleSystem(world: World, events: UIEventQueue): SystemDef {
const shown = new EntityStateMap<UIToggleData>();
// The interaction layer defines what a click is (release over the pressed
// entity); the toggle just listens.
events.on(UIEventType.Click, (ev) => {
const e = ev.target;
if (!world.valid(e) || !world.has(e, UIToggle)) return;
if (world.has(e, Interactable)
&& !(world.get(e, Interactable) as InteractableData).enabled) return;
const d = world.get(e, UIToggle) as UIToggleData;
const group = groupOf(world, e);
// A group that must keep a selection ignores a click on the selected
// one; otherwise the tab bar can be clicked into showing nothing.
if (group && d.isOn
&& !(world.get(group, UIToggleGroup) as UIToggleGroupData).allowSwitchOff) return;
d.isOn = !d.isOn;
world.insert(e, UIToggle, d);
if (group && d.isOn) clearSiblings(world, group, e);
});
return defineSystem([], () => {
for (const e of world.getEntitiesWithComponents([UIToggle])) {
if (!world.valid(e) || !world.has(e, UIToggle)) continue;
const d = world.get(e, UIToggle) as UIToggleData;
const previous = shown.get(e);
if (previous && previous.isOn === d.isOn && previous.check === d.check) continue;
const emitChange = previous !== undefined && previous.isOn !== d.isOn;
if (previous) {
previous.isOn = d.isOn; previous.check = d.check;
} else {
shown.set(e, { isOn: d.isOn, check: d.check });
}
setUIVisible(world, d.check, d.isOn);
if (emitChange) events.emit(e, UIEventType.Change, { isOn: d.isOn });
}
shown.cleanup(world);
}, { name: 'UIToggleSystem' });
}