From 8945e84ada5790c1596de8ff27fa10ec231b134a Mon Sep 17 00:00:00 2001 From: Yi C Date: Thu, 16 Apr 2026 17:19:22 -0700 Subject: [PATCH 1/3] fix(input): add META_LEFT/META_RIGHT keycode support for macOS CMD key (#18466) On macOS, pressing the CMD (Meta) key incorrectly reported keyCode 0 (unknown) instead of the correct values. This adds the missing META_LEFT (91) and META_RIGHT (93) enum values to the TypeScript KeyCode enum, and the corresponding mappings in both web and native keyboard input handlers. Closes #18466 Co-Authored-By: Claude Opus 4.6 --- cocos/input/types/key-code.ts | 12 ++++++++++++ pal/input/keycodes.ts | 2 ++ pal/input/native/keyboard-input.ts | 2 ++ 3 files changed, 16 insertions(+) diff --git a/cocos/input/types/key-code.ts b/cocos/input/types/key-code.ts index a68557cf02d..481fcda78bd 100644 --- a/cocos/input/types/key-code.ts +++ b/cocos/input/types/key-code.ts @@ -375,6 +375,18 @@ export enum KeyCode { */ KEY_Z = 90, + /** + * @en The left meta key (CMD on macOS, Windows key on Windows) + * @zh 左 Meta 键（macOS 上的 CMD 键，Windows 上的 Windows 键） + */ + META_LEFT = 91, + + /** + * @en The right meta key (CMD on macOS, Windows key on Windows) + * @zh 右 Meta 键（macOS 上的 CMD 键，Windows 上的 Windows 键） + */ + META_RIGHT = 93, + /** * @en The numeric keypad 0 * @zh 数字键盘 0 diff --git a/pal/input/keycodes.ts b/pal/input/keycodes.ts index 8159e43ae5d..ab092f67192 100644 --- a/pal/input/keycodes.ts +++ b/pal/input/keycodes.ts @@ -10,6 +10,8 @@ export const code2KeyCode: Record = { ShiftRight: KeyCode.SHIFT_RIGHT, ControlRight: KeyCode.CTRL_RIGHT, AltRight: KeyCode.ALT_RIGHT, + MetaLeft: KeyCode.META_LEFT, + MetaRight: KeyCode.META_RIGHT, Pause: KeyCode.PAUSE, CapsLock: KeyCode.CAPS_LOCK, Escape: KeyCode.ESCAPE, diff --git a/pal/input/native/keyboard-input.ts b/pal/input/native/keyboard-input.ts index c36375b7c6f..0f645c75c76 100644 --- a/pal/input/native/keyboard-input.ts +++ b/pal/input/native/keyboard-input.ts @@ -45,6 +45,8 @@ const nativeKeyCode2KeyCode: Record = { 20016: KeyCode.SHIFT_RIGHT, 20017: KeyCode.CTRL_RIGHT, 20018: KeyCode.ALT_RIGHT, + 91: KeyCode.META_LEFT, + 93: KeyCode.META_RIGHT, }; function getKeyCode (event: jsb.KeyboardEvent): KeyCode { From 75167b29abc6e5a12496a05942f0184f474282fa Mon Sep 17 00:00:00 2001 From: Yi C Date: Thu, 16 Apr 2026 17:24:18 -0700 Subject: [PATCH 2/3] test(input): add verification for META_LEFT/META_RIGHT keycode fix Add standalone verification script (verify-meta-key-fix.mjs) that validates the complete keycode chain from macOS native layer through to TypeScript, covering 29 checks across all 6 layers of the input pipeline. Also add Jest test file for when the test infrastructure is fixed. Co-Authored-By: Claude Opus 4.6 --- tests/pal/input-keycode.test.ts | 64 ++++++++++++++++++ verify-meta-key-fix.mjs | 112 ++++++++++++++++++++++++++++++++ 2 files changed, 176 insertions(+) create mode 100644 tests/pal/input-keycode.test.ts create mode 100644 verify-meta-key-fix.mjs diff --git a/tests/pal/input-keycode.test.ts b/tests/pal/input-keycode.test.ts new file mode 100644 index 00000000000..8fd64ba5806 --- /dev/null +++ b/tests/pal/input-keycode.test.ts @@ -0,0 +1,64 @@ +import { KeyCode } from '../../cocos/input/types/key-code'; +import { code2KeyCode } from '../../pal/input/keycodes'; + +describe('KeyCode enum', () => { + test('META_LEFT should be defined as 91', () => { + expect(KeyCode.META_LEFT).toBe(91); + }); + + test('META_RIGHT should be defined as 93', () => { + expect(KeyCode.META_RIGHT).toBe(93); + }); + + test('META_LEFT should match C++ EngineEvents.h value', () => { + // C++ side: META_LEFT = 91 (EngineEvents.h:233) + expect(KeyCode.META_LEFT).toBe(91); + }); + + test('META_RIGHT should match C++ EngineEvents.h value', () => { + // C++ side: META_RIGHT = 93 (EngineEvents.h:236) + expect(KeyCode.META_RIGHT).toBe(93); + }); + + test('META_LEFT and META_RIGHT should not conflict with adjacent enum values', () => { + // KEY_Z = 90, META_LEFT = 91, META_RIGHT = 93, NUM_0 = 96 + expect(KeyCode.KEY_Z).toBe(90); + expect(KeyCode.META_LEFT).toBe(91); + expect(KeyCode.META_RIGHT).toBe(93); + expect(KeyCode.NUM_0).toBe(96); + // Verify no collision + expect(KeyCode.META_LEFT).not.toBe(KeyCode.KEY_Z); + expect(KeyCode.META_LEFT).not.toBe(KeyCode.META_RIGHT); + expect(KeyCode.META_RIGHT).not.toBe(KeyCode.NUM_0); + }); +}); + +describe('code2KeyCode mapping', () => { + test('MetaLeft should map to KeyCode.META_LEFT (91)', () => { + expect(code2KeyCode.MetaLeft).toBe(KeyCode.META_LEFT); + expect(code2KeyCode.MetaLeft).toBe(91); + }); + + test('MetaRight should map to KeyCode.META_RIGHT (93)', () => { + expect(code2KeyCode.MetaRight).toBe(KeyCode.META_RIGHT); + expect(code2KeyCode.MetaRight).toBe(93); + }); + + test('MetaLeft/MetaRight should follow the same pattern as other modifier keys', () => { + // All modifier keys should have left/right variants mapped + expect(code2KeyCode.ShiftLeft).toBe(KeyCode.SHIFT_LEFT); + expect(code2KeyCode.ShiftRight).toBe(KeyCode.SHIFT_RIGHT); + expect(code2KeyCode.ControlLeft).toBe(KeyCode.CTRL_LEFT); + expect(code2KeyCode.ControlRight).toBe(KeyCode.CTRL_RIGHT); + expect(code2KeyCode.AltLeft).toBe(KeyCode.ALT_LEFT); + expect(code2KeyCode.AltRight).toBe(KeyCode.ALT_RIGHT); + expect(code2KeyCode.MetaLeft).toBe(KeyCode.META_LEFT); + expect(code2KeyCode.MetaRight).toBe(KeyCode.META_RIGHT); + }); + + test('MetaLeft/MetaRight should not be undefined', () => { + // This was the original bug - these mappings were missing + expect(code2KeyCode.MetaLeft).toBeDefined(); + expect(code2KeyCode.MetaRight).toBeDefined(); + }); +}); diff --git a/verify-meta-key-fix.mjs b/verify-meta-key-fix.mjs new file mode 100644 index 00000000000..41f74d7b6f1 --- /dev/null +++ b/verify-meta-key-fix.mjs @@ -0,0 +1,112 @@ +/** + * Standalone verification for META_LEFT/META_RIGHT fix (#18466) + * Run: node verify-meta-key-fix.mjs + * + * This script directly reads and parses source files to verify the fix, + * without needing the full engine build environment. + */ + +import { readFileSync } from 'fs'; + +let passed = 0; +let failed = 0; + +function assert(condition, msg) { + if (condition) { console.log(` ✅ PASS: ${msg}`); passed++; } + else { console.log(` ❌ FAIL: ${msg}`); failed++; } +} + +console.log('\n=== Verifying META_LEFT/META_RIGHT fix (Issue #18466) ===\n'); + +// ── 1. Check KeyCode enum in key-code.ts ── +console.log('1. KeyCode enum (cocos/input/types/key-code.ts):'); +const keyCodeSrc = readFileSync('cocos/input/types/key-code.ts', 'utf-8'); +const metaLeftMatch = keyCodeSrc.match(/META_LEFT\s*=\s*(\d+)/); +const metaRightMatch = keyCodeSrc.match(/META_RIGHT\s*=\s*(\d+)/); +assert(metaLeftMatch !== null, 'META_LEFT enum value exists'); +assert(metaLeftMatch?.[1] === '91', `META_LEFT = ${metaLeftMatch?.[1]} (expected 91)`); +assert(metaRightMatch !== null, 'META_RIGHT enum value exists'); +assert(metaRightMatch?.[1] === '93', `META_RIGHT = ${metaRightMatch?.[1]} (expected 93)`); + +// Verify numeric ordering: KEY_Z=90, META_LEFT=91, META_RIGHT=93, NUM_0=96 +const keyZMatch = keyCodeSrc.match(/KEY_Z\s*=\s*(\d+)/); +const num0Match = keyCodeSrc.match(/NUM_0\s*=\s*(\d+)/); +assert(keyZMatch?.[1] === '90', `KEY_Z = ${keyZMatch?.[1]} (expected 90)`); +assert(num0Match?.[1] === '96', `NUM_0 = ${num0Match?.[1]} (expected 96)`); + +// Verify META_LEFT is placed AFTER KEY_Z and BEFORE NUM_0 in the file +const keyZPos = keyCodeSrc.indexOf('KEY_Z = 90'); +const metaLeftPos = keyCodeSrc.indexOf('META_LEFT = 91'); +const metaRightPos = keyCodeSrc.indexOf('META_RIGHT = 93'); +const num0Pos = keyCodeSrc.indexOf('NUM_0 = 96'); +assert(keyZPos < metaLeftPos && metaLeftPos < metaRightPos && metaRightPos < num0Pos, + 'Enum placement order: KEY_Z(90) < META_LEFT(91) < META_RIGHT(93) < NUM_0(96)'); + +// ── 2. Check code2KeyCode mapping in keycodes.ts ── +console.log('\n2. Web mapping (pal/input/keycodes.ts):'); +const keycodesSrc = readFileSync('pal/input/keycodes.ts', 'utf-8'); +assert(keycodesSrc.includes('MetaLeft: KeyCode.META_LEFT'), 'MetaLeft → KeyCode.META_LEFT mapping exists'); +assert(keycodesSrc.includes('MetaRight: KeyCode.META_RIGHT'), 'MetaRight → KeyCode.META_RIGHT mapping exists'); + +// Verify all modifier keys have mappings (completeness check) +const modifierPairs = [ + ['ShiftLeft', 'SHIFT_LEFT'], ['ShiftRight', 'SHIFT_RIGHT'], + ['ControlLeft', 'CTRL_LEFT'], ['ControlRight', 'CTRL_RIGHT'], + ['AltLeft', 'ALT_LEFT'], ['AltRight', 'ALT_RIGHT'], + ['MetaLeft', 'META_LEFT'], ['MetaRight', 'META_RIGHT'], +]; +for (const [code, keycode] of modifierPairs) { + assert(keycodesSrc.includes(`${code}: KeyCode.${keycode}`), + `${code} → KeyCode.${keycode}`); +} + +// ── 3. Check nativeKeyCode2KeyCode in keyboard-input.ts ── +console.log('\n3. Native fallback (pal/input/native/keyboard-input.ts):'); +const nativeKbSrc = readFileSync('pal/input/native/keyboard-input.ts', 'utf-8'); +assert(nativeKbSrc.includes('91: KeyCode.META_LEFT'), 'Native keyCode 91 → KeyCode.META_LEFT'); +assert(nativeKbSrc.includes('93: KeyCode.META_RIGHT'), 'Native keyCode 93 → KeyCode.META_RIGHT'); + +// ── 4. Verify C++ side consistency ── +console.log('\n4. C++ native layer consistency (native/cocos/engine/EngineEvents.h):'); +const engineEventsSrc = readFileSync('native/cocos/engine/EngineEvents.h', 'utf-8'); +const cppMetaLeft = engineEventsSrc.match(/META_LEFT\s*=\s*(\d+)/); +const cppMetaRight = engineEventsSrc.match(/META_RIGHT\s*=\s*(\d+)/); +assert(cppMetaLeft?.[1] === '91', `C++ META_LEFT = ${cppMetaLeft?.[1]} (expected 91)`); +assert(cppMetaRight?.[1] === '93', `C++ META_RIGHT = ${cppMetaRight?.[1]} (expected 93)`); +assert(metaLeftMatch?.[1] === cppMetaLeft?.[1], `TS META_LEFT (${metaLeftMatch?.[1]}) === C++ META_LEFT (${cppMetaLeft?.[1]})`); +assert(metaRightMatch?.[1] === cppMetaRight?.[1], `TS META_RIGHT (${metaRightMatch?.[1]}) === C++ META_RIGHT (${cppMetaRight?.[1]})`); + +// ── 5. Verify JSB adapter handles 91/93 ── +console.log('\n5. JSB adapter (platforms/native/builtin/jsb-adapter/KeyboardEvent.js):'); +const jsbSrc = readFileSync('platforms/native/builtin/jsb-adapter/KeyboardEvent.js', 'utf-8'); +assert(jsbSrc.includes("keyCode === 91") && jsbSrc.includes("'MetaLeft'"), + 'JSB adapter maps keyCode 91 → MetaLeft'); +assert(jsbSrc.includes("keyCode === 93") && jsbSrc.includes("'MetaRight'"), + 'JSB adapter maps keyCode 93 → MetaRight'); + +// ── 6. Verify macOS KeyCodeHelper maps SUPER keys to 91/93 ── +console.log('\n6. macOS KeyCodeHelper (native/cocos/platform/mac/KeyCodeHelper.cpp):'); +const keyCodeHelperSrc = readFileSync('native/cocos/platform/mac/KeyCodeHelper.cpp', 'utf-8'); +assert(keyCodeHelperSrc.includes('GLFW_KEY_LEFT_SUPER') && keyCodeHelperSrc.includes('91'), + 'GLFW_KEY_LEFT_SUPER → 91'); +assert(keyCodeHelperSrc.includes('GLFW_KEY_RIGHT_SUPER') && keyCodeHelperSrc.includes('93'), + 'GLFW_KEY_RIGHT_SUPER → 93'); + +// ── 7. Bug reproduction: simulate the data flow ── +console.log('\n7. End-to-end data flow simulation:'); +console.log(' macOS CMD press → native keyCode=91 → JSB code="MetaLeft" → code2KeyCode → KeyCode.META_LEFT=91'); +assert(metaLeftMatch?.[1] === '91' && keycodesSrc.includes('MetaLeft: KeyCode.META_LEFT'), + 'Full chain: CMD Left → keyCode 91 (was 0 before fix)'); +assert(metaRightMatch?.[1] === '93' && keycodesSrc.includes('MetaRight: KeyCode.META_RIGHT'), + 'Full chain: CMD Right → keyCode 93 (was 0 before fix)'); + +// ── Summary ── +console.log(`\n${'='.repeat(55)}`); +console.log(`Results: ${passed} passed, ${failed} failed, ${passed + failed} total`); +if (failed === 0) { + console.log('🎉 All checks passed! META_LEFT/META_RIGHT fix verified.'); + console.log(' The full keycode chain from macOS native → TypeScript is now connected.\n'); +} else { + console.log('💥 Some checks failed!\n'); + process.exit(1); +} From 028dd4d4cdddc6e516d35450c94bb4dfdf5df333 Mon Sep 17 00:00:00 2001 From: Yi C Date: Thu, 16 Apr 2026 19:33:24 -0700 Subject: [PATCH 3/3] fix(input): suppress pre-existing no-console lint error in keyboard-input The ESLint CI checks all files touched by the PR diff. This file's pre-existing console.error (for unknown key codes) triggers the no-console rule. Add eslint-disable-next-line to unblock CI. Co-Authored-By: Claude Opus 4.6 --- pal/input/native/keyboard-input.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/pal/input/native/keyboard-input.ts b/pal/input/native/keyboard-input.ts index 0f645c75c76..f2bb23b20da 100644 --- a/pal/input/native/keyboard-input.ts +++ b/pal/input/native/keyboard-input.ts @@ -54,6 +54,7 @@ function getKeyCode (event: jsb.KeyboardEvent): KeyCode { if (event.code in code2KeyCode) { return code2KeyCode[event.code]; } else { + // eslint-disable-next-line no-console console.error(`Can not find keyCode for code: ${event.code}`); } }