benface · Nov 14, 2026
diff --git a/js/gl.js b/js/gl.js
@@ -1238,7 +1238,10 @@ var importObject = {
                 if (event.altKey) {
                     modifiers |= SAPP_MODIFIER_ALT;
                 }
-                wasm_exports.key_down(sapp_key_code, modifiers, event.repeat);
+                // `key` is one character, or a name like "Shift" or "Dead".
+                var characters = Array.from(event.key);
+                var character = characters.length == 1 ? characters[0].codePointAt(0) : 0;
+                wasm_exports.key_down(sapp_key_code, modifiers, event.repeat, character);
                 // for "space", "quote", and "slash" preventDefault will prevent
                 // key_press event, so send it here instead
                 if (sapp_key_code == 32 || sapp_key_code == 39 || sapp_key_code == 47) {

diff --git a/src/event.rs b/src/event.rs
@@ -181,8 +181,28 @@ pub trait EventHandler {
 
     fn char_event(&mut self, _character: char, _keymods: KeyMods, _repeat: bool) {}
 
+    /// `keycode` is the key's place on the keyboard, on most platforms: the key
+    /// in that place on a US QWERTY layout. See
+    /// [`key_down_with_character_event`](Self::key_down_with_character_event)
+    /// for what the key types on the user's layout.
     fn key_down_event(&mut self, _keycode: KeyCode, _keymods: KeyMods, _repeat: bool) {}
 
+    /// A key went down, with `character`, what it types on the keyboard's
+    /// current layout as Shift, and Command on macOS, change it, but not
+    /// Control: `'z'` for Ctrl+Z, and for Cmd+Z on a French AZERTY layout, whose
+    /// Z is where QWERTY has W. It's `None` when the key types no character, or
+    /// several, or the platform doesn't say. Unless implemented, it hands the
+    /// key on to [`key_down_event`](Self::key_down_event).
+    fn key_down_with_character_event(
+        &mut self,
+        keycode: KeyCode,
+        _character: Option<char>,
+        keymods: KeyMods,
+        repeat: bool,
+    ) {
+        self.key_down_event(keycode, keymods, repeat);
+    }
+
     /// Note: you are not always guaranteed to receive a key_up event. For example on
     /// Wayland when leaving the focused window, the key_up event will not be caught.
     fn key_up_event(&mut self, _keycode: KeyCode, _keymods: KeyMods) {}

diff --git a/src/native/android.rs b/src/native/android.rs
@@ -220,8 +220,12 @@ impl MainThreadState {
                     KeyCode::LeftSuper | KeyCode::RightSuper => self.keymods.logo = true,
                     _ => {}
                 }
-                self.event_handler
-                    .key_down_event(keycode, self.keymods, false);
+                self.event_handler.key_down_with_character_event(
+                    keycode,
+                    None,
+                    self.keymods,
+                    false,
+                );
             }
             Message::KeyUp { keycode } => {
                 match keycode {

diff --git a/src/native/apple/apple_util.rs b/src/native/apple/apple_util.rs
@@ -143,6 +143,31 @@ pub fn get_event_char(event: ObjcId) -> Option<char> {
     }
 }
 
+/// The one character `event`'s key types on the current layout with the event's
+/// Shift and Command, as macOS matches menu shortcuts, so that a layout that
+/// types QWERTY's letters while Command is held is followed.
+pub fn get_event_key_character(event: ObjcId) -> Option<char> {
+    unsafe {
+        let applies_modifiers: bool =
+            msg_send![event, respondsToSelector: sel!(charactersByApplyingModifiers:)];
+        let characters: ObjcId = if applies_modifiers {
+            let flags: u64 = msg_send![event, modifierFlags];
+            let kept = NSEventModifierFlags::NSShiftKeyMask as u64
+                | NSEventModifierFlags::NSCommandKeyMask as u64;
+            msg_send![event, charactersByApplyingModifiers: flags & kept]
+        } else {
+            // Before macOS 10.15.
+            msg_send![event, charactersIgnoringModifiers]
+        };
+        if characters == nil {
+            return None;
+        }
+        let characters = nsstring_to_string(characters);
+        let mut chars = characters.chars();
+        chars.next().filter(|_| chars.next().is_none())
+    }
+}
+
 pub fn get_event_key_modifier(event: ObjcId) -> KeyMods {
     let flags: u64 = unsafe { msg_send![event, modifierFlags] };
     KeyMods {

diff --git a/src/native/ios.rs b/src/native/ios.rs
@@ -137,7 +137,7 @@ fn dispatch_message(payload: &mut IosDisplay, msg: Message) {
                 state.keymods
             };
             if let Some(ref mut event_handler) = payload.event_handler {
-                event_handler.key_down_event(keycode, keymods, false);
+                event_handler.key_down_with_character_event(keycode, None, keymods, false);
             }
         }
         Message::KeyUp { keycode } => {

diff --git a/src/native/linux_wayland.rs b/src/native/linux_wayland.rs
@@ -298,15 +298,14 @@ impl KeyboardContext {
         // The keycodes in Miniquad are obtained without modifiers
         let keysym = libxkb.keymap_key_get_sym_without_mod(keymap.xkb_keymap, key + 8);
         let keycode = keycodes::translate_keysym(keysym);
-        events.push(WaylandEvent::KeyDown(keycode, keymods, repeat));
 
         // To obtain the underlying character, we do need to provide the modifiers
         let keysym = (libxkb.xkb_state_key_get_one_sym)(xkb_state, key + 8);
         let chr = (libxkb.xkb_keysym_to_utf32)(keysym);
-        if chr > 0 {
-            if let Some(chr) = char::from_u32(chr) {
-                events.push(WaylandEvent::Char(chr, keymods, repeat));
-            }
+        let character = char::from_u32(chr).filter(|_| chr > 0);
+        events.push(WaylandEvent::KeyDown(keycode, character, keymods, repeat));
+        if let Some(chr) = character {
+            events.push(WaylandEvent::Char(chr, keymods, repeat));
         }
     }
 }
@@ -530,7 +529,7 @@ unsafe extern "C" fn seat_handle_capabilities(
 }
 
 enum WaylandEvent {
-    KeyDown(KeyCode, KeyMods, bool),
+    KeyDown(KeyCode, Option<char>, KeyMods, bool),
     KeyUp(KeyCode, KeyMods),
     Char(char, KeyMods, bool),
     PointerMotion(f32, f32),
@@ -1258,9 +1257,8 @@ where
 
             for event in display.events.drain(..) {
                 match event {
-                    WaylandEvent::KeyDown(keycode, keymods, repeat) => {
-                        event_handler.key_down_event(keycode, keymods, repeat)
-                    }
+                    WaylandEvent::KeyDown(keycode, character, keymods, repeat) => event_handler
+                        .key_down_with_character_event(keycode, character, keymods, repeat),
                     WaylandEvent::KeyUp(keycode, keymods) => {
                         event_handler.key_up_event(keycode, keymods)
                     }

diff --git a/src/native/linux_x11.rs b/src/native/linux_x11.rs
@@ -73,12 +73,11 @@ impl X11Display {
                     std::ptr::null_mut(),
                 );
                 let chr = keycodes::keysym_to_unicode(&mut self.libxkbcommon, keysym);
-                if chr > 0 {
-                    if let Some(chr) = char::from_u32(chr as u32) {
-                        event_handler.char_event(chr, mods, repeat);
-                    }
+                let character = char::from_u32(chr as u32).filter(|_| chr > 0);
+                if let Some(chr) = character {
+                    event_handler.char_event(chr, mods, repeat);
                 }
-                event_handler.key_down_event(key, mods, repeat);
+                event_handler.key_down_with_character_event(key, character, mods, repeat);
             }
             3 => {
                 let keycode = event.xkey.keycode;

diff --git a/src/native/macos.rs b/src/native/macos.rs
@@ -634,8 +634,9 @@ unsafe fn view_base_decl(decl: &mut ClassDecl) {
         let mods = get_event_key_modifier(event);
         let repeat: bool = unsafe { msg_send!(event, isARepeat) };
         if let Some(key) = get_event_keycode(event) {
+            let character = get_event_key_character(event);
             if let Some(event_handler) = payload.context() {
-                event_handler.key_down_event(key, mods, repeat);
+                event_handler.key_down_with_character_event(key, character, mods, repeat);
             }
         }
 
@@ -736,7 +737,7 @@ unsafe fn view_base_decl(decl: &mut ClassDecl) {
             if new_pressed ^ old_pressed {
                 if new_pressed {
                     if let Some(event_handler) = payload.context() {
-                        event_handler.key_down_event(keycode, mods, false);
+                        event_handler.key_down_with_character_event(keycode, None, mods, false);
                     }
                 } else {
                     if let Some(event_handler) = payload.context() {

diff --git a/src/native/wasm.rs b/src/native/wasm.rs
@@ -282,12 +282,13 @@ pub extern "C" fn mouse_wheel(dx: i32, dy: i32) {
 }
 
 #[no_mangle]
-pub extern "C" fn key_down(key: u32, modifiers: u32, repeat: bool) {
+pub extern "C" fn key_down(key: u32, modifiers: u32, repeat: bool, character: u32) {
     let key = keycodes::translate_keycode(key as _);
     let mods = keycodes::translate_mod(modifiers as _);
+    let character = char::from_u32(character).filter(|_| character > 0);
 
     tl_event_handler(|event_handler| {
-        event_handler.key_down_event(key, mods, repeat);
+        event_handler.key_down_with_character_event(key, character, mods, repeat);
     });
 }
 

diff --git a/src/native/windows.rs b/src/native/windows.rs
@@ -250,7 +250,7 @@
        if unsafe { GetClientRect(self.wnd, &mut rect as *mut _ as _) } != 0 {
            let mut new_rect = rect;
            new_rect.right = new_rect.right - new_rect.left + new_x as i32;
            new_rect.bottom = new_rect.bottom - new_rect.top + new_y as i32;
            unsafe {
                SetWindowPos(
                    self.wnd,
@@ -371,6 +371,35 @@
     mods
 }
 
+/// The one character the virtual key `vk` types on the current layout, with
+/// Shift held or not and no other modifier.
+unsafe fn key_character(vk: UINT, scancode: UINT, shift: bool) -> Option<char> {
+    let mut state = [0u8; 256];
+    if shift {
+        state[VK_SHIFT as usize] = 0x80;
+    }
+    let mut typed = [0u16; 8];
+    // Leaves the keyboard's state alone, so a dead key still reaches WM_CHAR.
+    const KEEP_KEYBOARD_STATE: UINT = 0x4;
+    let length = ToUnicodeEx(
+        vk,
+        scancode,
+        state.as_ptr(),
+        typed.as_mut_ptr(),
+        typed.len() as _,
+        KEEP_KEYBOARD_STATE,
+        GetKeyboardLayout(0),
+    );
+    if length <= 0 {
+        return None;
+    }
+    let mut chars = char::decode_utf16(typed[..length as usize].iter().copied());
+    match (chars.next(), chars.next()) {
+        (Some(Ok(character)), None) => Some(character),
+        _ => None,
+    }
+}
+
 unsafe extern "system" fn win32_wndproc(
     hwnd: HWND,
     umsg: UINT,
@@ -695,7 +724,8 @@
             let keycode = keycodes::translate_keycode(keycode_raw);
             let mods = key_mods();
             let repeat = !!(lparam & 0x40000000) != 0;
-            event_handler.key_down_event(keycode, mods, repeat);
+            let character = key_character(wparam as UINT, keycode_raw, mods.shift);
+            event_handler.key_down_with_character_event(keycode, character, mods, repeat);
             // Pass to DefWindowProc for IME to work properly
             return DefWindowProcW(hwnd, umsg, wparam, lparam);
         }