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.

fix(example): return training keyboard focus when play resumes

yhhfae1fd355a04
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 07174d356..91b120dff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Training resumes with gameplay keyboard focus.** Starting or resuming a round releases the menu control's focus, updates its Focusable state and emits Blur, so Space fires instead of reopening a rewarded break after an ad. Blur callbacks remain effective and menu buttons retain keyboard navigation.
+
- **Tile collision previews follow unsaved tileset edits and undo.** Editor outline models read the open tileset document and refresh on relevant document edits, undo/redo, disk changes and project switches. Ordinary scene edits and unrelated documents retain the cached model; obsolete requests stop loading later tilesets and cannot publish into the new preview. Closing a document restores the saved asset's collision metadata.
- **Windowed editor lists attach to the scroller that actually mounted.** Resource grids and shared virtual windows subscribe after ancestor refs are available, reattach when their elements change, and retain scroll and size observation through StrictMode cleanup. Large lists keep updating visible rows instead of remaining on the first batch or using a single fallback column.
diff --git a/examples/mobile-controls/src/main.ts b/examples/mobile-controls/src/main.ts
index bda4a1054..f400a8002 100644
--- a/examples/mobile-controls/src/main.ts
+++ b/examples/mobile-controls/src/main.ts
@@ -2,7 +2,7 @@ import {
addStartupSystem, addSystemToSchedule, defineSystem, Schedule, Res, GetWorld,
Input, InputMap, Axis2D, Button, Keys2D, Key, Virtual, Time, Transform, Sprite,
UIEvents, Text, Name, UINode, UIPositionType, spawnUIEntity, createButton, px, Device,
- Ads, type World, type Entity, type DeviceResult,
+ Ads, FocusManager, type World, type Entity, type DeviceResult,
} from 'esengine';
import { setupWebTraining } from './pokiTrainingUI';
import type { TrainingSession } from './pokiTraining';
@@ -30,7 +30,7 @@ const refreshStatus = (world: World): void => {
if (world.get(status, Text).content !== content) world.insert(status, Text, { ...world.get(status, Text), content });
};
-addStartupSystem(defineSystem([Res(UIEvents), Res(Ads), GetWorld()], (events, ads, world) => {
+addStartupSystem(defineSystem([Res(UIEvents), Res(Ads), Res(FocusManager), GetWorld()], (events, ads, focus, world) => {
const canvas = world.findEntityByName('Canvas'); if (canvas === null) return;
spawnUIEntity({ world, parent: canvas,
node: { position: UIPositionType.Absolute, insetLeft: px(30), insetTop: px(6), width: px(740), height: px(22), pointerEvents: 1 },
@@ -83,7 +83,7 @@ addStartupSystem(defineSystem([Res(UIEvents), Res(Ads), GetWorld()], (events, ad
transform.scale = { x: 1, y: 1, z: 1 }; world.insert(entity, Transform, transform);
world.insert(entity, Sprite, { ...world.get(entity, Sprite), color: { r: 1, g: 1, b: 1, a: 1 } });
}
- }, () => refreshStatus(world));
+ }, () => refreshStatus(world), focus);
refreshStatus(world);
}
}, { name: 'MobileControlsSetup' }));
diff --git a/examples/mobile-controls/src/pokiTrainingUI.ts b/examples/mobile-controls/src/pokiTrainingUI.ts
index 6ead578c0..4c2704ef6 100644
--- a/examples/mobile-controls/src/pokiTrainingUI.ts
+++ b/examples/mobile-controls/src/pokiTrainingUI.ts
@@ -1,15 +1,16 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { createButton, spawnUIEntity, Text, Name, UIPositionType, px, Storage, Scores, type AdsAPI } from 'esengine';
+import { createButton, spawnUIEntity, Text, Name, UIPositionType, px, Storage, Scores, type AdsAPI, type FocusManagerState } from 'esengine';
import { TrainingSession } from './pokiTraining';
import { TrainingSave } from './trainingSave';
+import { releaseTrainingFocus } from './trainingFocus';
type ButtonOptions = Parameters<typeof createButton>[0];
interface PokiGameplay { gameplayStart(): void; gameplayStop(): void }
export function setupWebTraining(
world: ButtonOptions['world'], events: ButtonOptions['events'], parent: NonNullable<ButtonOptions['parent']>,
- ads: AdsAPI, reset: () => void, refresh: () => void,
+ ads: AdsAPI, reset: () => void, refresh: () => void, focus: FocusManagerState,
): TrainingSession | null {
if (typeof document === 'undefined') return null;
const channel = document.documentElement?.dataset?.webChannel;
@@ -38,7 +39,8 @@ export function setupWebTraining(
refresh();
};
const session = new TrainingSession(ads, {
- gameplayStart: () => notify('gameplayStart'), gameplayStop: () => notify('gameplayStop'), reset, changed: update,
+ gameplayStart: () => { releaseTrainingFocus(world, events, focus); notify('gameplayStart'); },
+ gameplayStop: () => notify('gameplayStop'), reset, changed: update,
rewardGranted: credits => {
if (!save) return;
if (channel === 'youtube') {
diff --git a/examples/mobile-controls/src/trainingFocus.ts b/examples/mobile-controls/src/trainingFocus.ts
new file mode 100644
index 000000000..4aa7f85ec
--- /dev/null
+++ b/examples/mobile-controls/src/trainingFocus.ts
@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { Focusable, UIEventType, type FocusManagerState, type UIEventQueue, type World } from 'esengine';
+
+/** Returning to gameplay gives Space back to the game instead of the last menu button. */
+export function releaseTrainingFocus(world: World, events: UIEventQueue, focus: FocusManagerState): void {
+ const previous = focus.blur();
+ if (previous === null || !world.valid(previous) || !world.has(previous, Focusable)) return;
+ world.update(previous, Focusable, data => { data.isFocused = false; });
+ events.emit(previous, UIEventType.Blur);
+}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 40d1d9b8e..70c207533 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(example): return training keyboard focus when play resumes':
+ { note: 'Training resumes with gameplay keyboard focus.' },
'fix(editor): refresh tile collision previews from live metadata':
{ note: 'Tile collision previews follow unsaved tileset edits and undo.' },
'fix(editor): synchronize live tile collision preview metadata':
diff --git a/tools/tests/training-focus.test.ts b/tools/tests/training-focus.test.ts
new file mode 100644
index 000000000..37d8f9809
--- /dev/null
+++ b/tools/tests/training-focus.test.ts
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { expect, it, vi } from 'vitest';
+import { World } from '../../sdk/src/ecs/world';
+import { Focusable, FocusManagerState } from '../../sdk/src/ui/input/focusable';
+import { UIEventQueue } from '../../sdk/src/ui/core/events';
+vi.mock('esengine', async () => ({
+ Focusable: (await import('../../sdk/src/ui/input/focusable')).Focusable,
+ UIEventType: (await import('../../sdk/src/ui/core/events')).UIEventType,
+}));
+import { releaseTrainingFocus } from '../../examples/mobile-controls/src/trainingFocus';
+
+function fixture() {
+ const world = new World(), entity = world.spawn(), events = new UIEventQueue(), focus = new FocusManagerState();
+ world.insert(entity, Focusable, { isFocused: true }); focus.focus(entity, true);
+ return { world, entity, events, focus };
+}
+it('releases the menu focus and its component flag before notifying blur', () => {
+ const { world, entity, events, focus } = fixture();
+ const samples: unknown[] = [];
+ events.on(entity, 'blur', () => samples.push([focus.focusedEntity, world.get(entity, Focusable).isFocused]));
+ releaseTrainingFocus(world, events, focus);
+ expect(samples).toEqual([[null, false]]); expect(focus.focusVisible).toBe(false);
+});
+it('does not repeat blur for an already released focus', () => {
+ const { world, events, focus } = fixture();
+ releaseTrainingFocus(world, events, focus); events.drain();
+ releaseTrainingFocus(world, events, focus); expect(events.drain()).toEqual([]);
+});
+it('drops a destroyed focus target without reading its components', () => {
+ const { world, entity, events, focus } = fixture(); world.despawn(entity);
+ releaseTrainingFocus(world, events, focus); expect(focus.focusedEntity).toBeNull(); expect(events.drain()).toEqual([]);
+});
+it('preserves focus explicitly acquired by a blur handler', () => {
+ const { world, entity, events, focus } = fixture(), next = world.spawn(); world.insert(next, Focusable);
+ events.on(entity, 'blur', () => focus.focus(next, true));
+ releaseTrainingFocus(world, events, focus); expect(focus.focusedEntity).toBe(next);
+});