PR feedback

cleanup
chore: auto-format with clang-format
2026-07-27 16:47:11 -07:00 · 2026-04-10 23:48:45 -07:00 · 2026-04-10 23:48:45 -07:00 · 2026-04-11 06:30:12 +00:00 · 2026-04-10 23:21:41 -07:00 · 2026-04-10 07:53:46 -07:00
119 changed files with 5517 additions and 1842 deletions
@@ -17,15 +17,5 @@

 - *Preview builds are not available for pull requests from forked repositories.* To enable preview builds, submit the PR from a branch within this repository. 

- *Formatting issues? You have two options:*
-1. **Fix formatting automatically** using the following Docker command: *(If you're using Windows, remove `--user $(id -u):$(id -g)`)* 
-```bash
-docker run --rm \
-  -v $(pwd):/app --workdir /app  \
-  --user $(id -u):$(id -g) silkeh/clang:18 \
-  bash -c 'find src -type f -name \*.cc -o -name \*.h | xargs clang-format -i'
-```
-2. **Skip formatting check** by adding the `skip-formatting` label to this PR.
-
 --->

@@ -102,6 +102,8 @@ target_sources(${EXECUTABLE_NAME} PUBLIC
    "src/font_manager.h"
    "src/game_config.cc"
    "src/game_config.h"
+    "src/game_config_migration.cc"
+    "src/game_config_migration.h"
    "src/game_dialog.cc"
    "src/game_dialog.h"
    "src/game_memory.cc"
@@ -172,6 +174,8 @@ target_sources(${EXECUTABLE_NAME} PUBLIC
    "src/obj_types.h"
    "src/object.cc"
    "src/object.h"
+    "src/opcode_context.cc"
+    "src/opcode_context.h"
    "src/options.cc"
    "src/options.h"
    "src/palette.cc"
@@ -289,6 +293,8 @@ target_sources(${EXECUTABLE_NAME} PUBLIC
    "src/sfall_script_hooks.cc"
    "src/sfall_arrays.cc"
    "src/sfall_arrays.h"
+    "src/sfall_animation.cc"
+    "src/sfall_animation.h"
    "src/sfall_callbacks.cc"
    "src/sfall_callbacks.h"
    "src/touch.cc"
@@ -432,6 +438,7 @@ endif()

 add_subdirectory("third_party/fpattern")
 target_link_libraries(${EXECUTABLE_NAME} fpattern::fpattern)
+target_link_libraries(${EXECUTABLE_NAME} fpattern_windows::fpattern_windows)

 target_link_libraries(${EXECUTABLE_NAME} ${ZLIB_LIBRARIES})
 target_include_directories(${EXECUTABLE_NAME} PRIVATE ${ZLIB_INCLUDE_DIRS})
@@ -509,28 +516,3 @@ if(CMAKE_SYSTEM_NAME MATCHES "Emscripten")
    set(CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} -g")
    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g")
 endif()
-
-# Optional path to which the built executable and PDB will be copied after build.
-# Can be set via -DCOPY_TO_PATH=/some/path or through the CMake/CLion GUI.
-set(COPY_TO_PATH "" CACHE PATH "Destination directory for copying the executable and PDB after build")
-
-if(DEFINED COPY_TO_PATH AND NOT "${COPY_TO_PATH}" STREQUAL "")
-    add_custom_command(TARGET ${EXECUTABLE_NAME} POST_BUILD
-        COMMAND ${CMAKE_COMMAND} -E make_directory "${COPY_TO_PATH}"
-        COMMAND ${CMAKE_COMMAND} -E copy_if_different
-            "$<TARGET_FILE:${EXECUTABLE_NAME}>"
-            "${COPY_TO_PATH}/"
-        COMMAND ${CMAKE_COMMAND} -E echo "Copied executable to ${COPY_TO_PATH}"
-    )
-    if(MSVC)
-        add_custom_command(TARGET ${EXECUTABLE_NAME} POST_BUILD
-                COMMAND ${CMAKE_COMMAND} -E copy_if_different
-                "$<TARGET_PDB_FILE:${EXECUTABLE_NAME}>"
-                "${COPY_TO_PATH}/"
-                COMMAND ${CMAKE_COMMAND} -E echo "Copied PDB to ${COPY_TO_PATH}"
-        )
-        message(STATUS "Will copy executable and PDB to: ${COPY_TO_PATH}")
-    else()
-        message(STATUS "Will copy executable to: ${COPY_TO_PATH}")
-    endif()
-endif()
@@ -0,0 +1,20 @@
+# Contributing
+
+This file is currently a shell to be filled in over time. For now, it only captures project-specific maintenance notes that are easy to miss.
+
+## Updating SDL
+
+SDL is pinned for native builds in `third_party/sdl2/CMakeLists.txt`. Right now, Android also relies on checked-in Java bindings in `os/android/app/src/main/java/org/libsdl/app`, and those bindings must match the SDL version fetched by CMake.
+
+When updating SDL:
+
+1. Update the SDL tag in `third_party/sdl2/CMakeLists.txt`.
+2. Run an Android build once so Gradle/CMake fetch the new SDL source tree.
+3. Copy the Android Java bindings from the fetched SDL checkout into `os/android/app/src/main/java/org/libsdl/app`.
+   Source path pattern:
+   `os/android/app/.cxx/<Variant>/<Hash>/arm64-v8a/_deps/sdl2-src/android-project/app/src/main/java/org/libsdl/app`
+4. Rebuild Android and confirm the SDL sync guard passes.
+
+The Android build contains a guard in `os/android/app/build.gradle` that fails if the checked-in Java bindings drift from the fetched native SDL source.
+
+This is a hack, not a good long-term setup. The Java bindings are still duplicated in the repo instead of being sourced from the same SDL tree as the native build. That should be improved so Android does not depend on a manual copy/sync step.
@@ -0,0 +1,106 @@
+# Sfall Compatibility
+
+This document tracks Fallout 2 CE compatibility with sfall.  This is for modders who need to know which Sfall features work in CE.
+
+For now, this covers opcodes/metarules, and hooks.  In the future, it will include other ways of modifying the engine (like ini files), and other Sfall-specific behaviour.
+
+## Opcodes / Metarules
+
+See [`https://sfall-team.github.io/sfall/`](https://sfall-team.github.io/sfall/) for documentation on specific functions.
+
+| Group | Opcodes In Group | Compatibility | Notes |
+| --- | --- | --- | --- |
+| Direct memory access| read_byte,short,int,string<br>write_byte,short,int,string<br>call_offset_vX | 🚫 | Not possible.  Open an issue if you need functionality not covered by other opcodes. |
+| Stats | get/set_pc_base_stat<br>get/set_pc_extra_stat<br>get/set_critter_base_stat<br>get/set_critter_extra_stat | ✅ | CE uses engine stat helpers here instead of sfall's direct proto-field behavior, so derived-stat update behavior can differ. |
+| Stats / Alter min/max | get/set_stat_min/max<br>set_pc_stat_min/max<br>set_npc_stat_min/max | not implemented | - |
+| Skills | get/set_critter_skill_points<br>get/set_available_skill_points<br>set_skill_max<br>set_critter_skill_mod<br>set_base_skill_mod<br>mod_skill_points_per_level | not implemented | - |
+| Graphics | graphics_funcs_available<br>force_graphics_refresh<br>get_screen_width<br>get_screen_height<br>set_palette | implemented: only get_screen_width, get_screen_height | - |
+| Shaders | load_shader<br>free_shader<br>activate_shader<br>deactivate_shader<br>set/get_shader_* | 🚫 | likely will not implement direct compatibility
+| Perks and traits | get_perk_owed<br>set_perk_owed<br>set_perk_image<br>set_perk_*<br>set_pyromaniac_mod<br>apply_heaveho_fix<br>set_swiftlearner_mod<br>has/set_fake_perk<br>has/set_fake_trait<br>set_selectable_perk<br>set_perkbox_title<br>show/hide_real_perks<br>perk_add_mode<br>clear_selectable_perks<br>add/remove_trait<br>seq_perk_freq | implemented: only get_perk_owed, set_perk_owed | - |
+| Virtual file system | fs_create<br>fs_copy<br>fs_find<br>fs_read/write_*<br>fs_delete<br>fs_size<br>fs_pos<br>fs_seek<br>fs_resize | 🚫 | Open an issue if you have a use case for these |
+| Combat / Knockback | set_weapon_knockback<br>set_target_knockback<br>set_attacker_knockback<br>remove_weapon_knockback<br>remove_target_knockback<br>remove_attacker_knockback | not implemented | - |
+| Maps and encounters | in_world_map<br>force_encounter<br>force_encounter_with_flags<br>set_map_time_multi<br>get/set_map_enter_position<br>exec_map_update_scripts<br>get/set_terrain_name<br>set_town_title<br>get/set_can_rest_on_map<br>set_rest_heal_time<br>set_rest_mode<br>set_worldmap_heal_time | implemented: in_world_map, force_encounter, force_encounter_with_flags, set_map_time_multi | - |
+| Maps and encounters / Worldmap | get_world_map_x/y_pos<br>set_world_map_pos | ✅ | - |
+| Audio | eax_available<br>set_eax_environment<br>play_sfall_sound<br>stop_sfall_sound | not implemented | *eax* opcodes will not be implemented |
+| Combat / Weapons and ammo | get/set_weapon_ammo_pid<br>get/set_weapon_ammo_count | ✅ | - |
+| Sfall / Version | sfall_ver_major<br>sfall_ver_minor<br>sfall_ver_build | ✅ | CE currently reports `4.3.4` |
+| Utility / Math | log, exponent, round, sqrt, abs, sin, cos, tan, arctan, ceil, ^, floor2, div | ✅ | - |
+| Keyboard and mouse | key_pressed<br>tap_key<br>get_mouse_x/y<br>get_mouse_buttons | ✅ | - |
+| Lists | list_begin<br>list_next<br>list_end<br>list_as_array<br>party_member_list | ✅ | - |
+| Explosions | set_attack_explosion_pattern<br>set_attack_explosion_art<br>set_attack_explosion_radius<br>set_attack_is_explosion_fire<br>set_explosion_radius<br>set_dynamite_damage<br>set_plastic_damage<br>get_explosion_damage<br>set_explosion_max_targets<br>item_make_explosive | ✅ except item_make_explosive | - |
+| Animations | reg_anim_combat_check<br>reg_anim_destroy<br>reg_anim_animate_and_hide<br>reg_anim_light<br>reg_anim_change_fid<br>reg_anim_take_out<br>reg_anim_turn_towards<br>reg_anim_callback<br>reg_anim_animate_and_move | ✅ except reg_anim_callback | - |
+| Art and appearance | art_exists<br>refresh_pc_art<br>art_cache_clear<br>set_hero_race<br>set_hero_style | implemented: art_exists, refresh_pc_art, art_cache_clear | - |
+| Tiles and paths | get_tile_fid<br>tile_under_cursor<br>tile_light<br>tile_get_objs<br>tile_refresh_display<br>obj_blocking_tile<br>tile_by_position<br>get_tile_ground_fid<br>get_tile_roof_fid<br>obj_blocking_line<br>path_find_to<br>objects_in_radius | ✅ except objects_in_radius | - |
+| Utility | sprintf<br>typeof<br>atoi<br>atof | ✅ | - |
+| Utility / Strings | string_split<br>substr<br>strlen<br>charcode<br>get_string_pointer<br>string_find<br>string_find_from<br>string_format<br>string_format_array<br>string_replace<br>string_to_case<br>string_compare | ✅ | `get_string_pointer` is deprecated and intentionally omitted. |
+| Interface / Tags | show_iface_tag<br>hide_iface_tag<br>is_iface_tag_active<br>set_iface_tag_text<br>add_iface_tag | ✅ except set_iface_tag_text, add_iface_tag | CE only handles built-in interface tags here; custom tag creation/text is not supported yet. |
+| Global variables | set_sfall_global<br>get_sfall_global_int<br>get_sfall_global_float | ✅ except get_sfall_global_float | Current CE storage is int-backed; `set_sfall_global` stores integer values |
+| Hooks / Hook functions | init_hook<br>get_sfall_arg<br>get_sfall_args<br>get_sfall_arg_at<br>set_sfall_return<br>set_sfall_arg<br>register_hook<br>register_hook_proc<br>register_hook_proc_spec | ✅ | See below for implemented hooks. `init_hook` is deprecated and will not be implemented. register_hook_proc and register_hook_proc_spec both add hooks to the *end* of the hook list, instead of beginning and end, respectively. |
+| Arrays / Array functions | create_array<br>temp_array<br>fix_array<br>get/set_array<br>resize_array<br>free_array<br>scan_array<br>len_array<br>save/load_array<br>array_key<br>arrayexpr | ✅ except save_array, load_array | - |
+| Perks and traits / NPC perks | set_fake_perk_npc<br>set_fake_trait_npc<br>set_selectable_perk_npc<br>has_fake_perk_npc<br>has_fake_trait_npc | not implemented | - |
+| Global scripts / Global script functions | set_global_script_repeat<br>set_global_script_type<br>available_global_script_types | ✅ except available_global_script_types | - |
+| Combat | attack_is_aimed<br>block_combat<br>force_aimed_shots<br>disable_aimed_shots<br>get_attack_type<br>get/set_bodypart_hit_modifier<br>combat_data<br>get/set/reset_critical_table<br>get_last_target<br>get_last_attacker<br>set_critter_burst_disable<br>get/set_critter_current_ap<br>set_spray_settings<br>get/set_combat_free_move | implemented: only get_attack_type, get_bodypart_hit_modifier, combat_data, set_bodypart_hit_modifier | - |
+| Car | set_car_current_town<br>car_gas_amount<br>set_car_intface_art | implemented: all except set_car_intface_art | - |
+| Interface / Windows and images | art_frame_data<br>interface_art_draw<br>interface_print<br>draw_image<br>draw_image_scaled<br>get_window_under_mouse<br>create_win<br>get_window_attribute<br>message_box<br>set_window_flag<br>win_fill_color<br>interface_overlay<br>dialog_message<br>get_text_width<br>hide_window<br>show_window<br>create_message_window | implemented: only message_box, get_text_width, show_window, create_message_window | - |
+| Interface / Outline | outlined_object<br>get_outline<br>set_outline | ✅ except get_outline | - |
+| Interface / Main interface | intface_is_hidden<br>intface_redraw<br>intface_hide<br>intface_show<br>set_quest_failure_value | implemented: only intface_redraw | `intface_redraw` only supports the zero-argument form; the optional-argument path is explicitly unimplemented. |
+| Interface / Inventory | display_stats<br>inventory_redraw<br>critter_inven_obj2<br>get_current_inven_size<br>item_weight | implemented: only critter_inven_obj2 | - |
+| Interface / Cursor | get/set_cursor_mode | ✅ | - |
+| Locks | lock_is_jammed<br>unjam_lock<br>set_unjam_locks_time | not implemented | - |
+| INI settings | get_ini_setting<br>get_ini_string<br>get_ini_section<br>get_ini_sections<br>get_ini_config<br>get_ini_config_db<br>set_ini_setting | ✅ except get_ini_config, get_ini_config_db | `modified_ini` is intentionally omitted as deprecated. |
+| Objects and scripts | set_self<br>set_dude_obj<br>real_dude_obj<br>remove_script<br>set_script<br>get_script<br>obj_is_carrying_obj<br>loot_obj<br>dialog_obj<br>obj_under_cursor<br>get_object_data<br>set_object_data<br>get_flags<br>set_flags<br>set_unique_id<br>set_scr_name<br>obj_is_openable<br>get/set_proto_data<br>get_object_ai_data | implemented: set_self, get_script, obj_is_carrying_obj, loot_obj, dialog_obj, obj_under_cursor, get_object_data, get_flags, set_flags, get_proto_data, set_proto_data | - |
+| Other / Game management | set_movie_path<br>stop_game<br>resume_game<br>mark_movie_played<br>game_loaded<br>get_game_mode<br>get_uptime<br>signal_close_game | implemented: game_loaded, get_game_mode, get_uptime, signal_close_game | - |
+| Gameplay tweaks | set_pickpocket_max<br>set_hit_chance_max<br>set_xp_mod<br>set_critter_hit_chance_mod<br>set_base_hit_chance_mod<br>set_hp_per_level_mod<br>get_unspent_ap_bonus<br>gdialog_get_barter_mod<br>set_unspent_ap_bonus<br>get/set_unspent_ap_perk_bonus<br>set_inven_ap_cost<br>set_base_pickpocket_mod<br>set_critter_pickpocket_mod<br>get_inven_ap_cost<br>set_drugs_data<br>get_kill_counter<br>mod_kill_counter<br>set_pipboy_available | not implemented | - |
+| NPCs | inc_npc_level<br>get_npc_level<br>npc_engine_level_up | not implemented | - |
+| Other | get_year<br>set_dm/df_model<br>active_hand<br>toggle_active_hand<br>get/set_viewport_x/y<br>hero_select_win<br>get_light_level<br>message_str_game<br>sneak_success<br>create_spatial<br>unwield_slot<br>add_g_timer_event<br>add_extra_msg_file<br>get_metarule_table<br>metarule_exist<br>remove_timer_event<br>spatial_radius | implemented: get_year, active_hand, toggle_active_hand, message_str_game, add_extra_msg_file, metarule_exist | `input_funcs_available`, `nb_create_char` are deprecated in sfall and intentionally absent in CE. `add_extra_msg_file` does not support the explicit `fileNumber` form in CE. |
+
+## Hooks
+
+| Hook | ID | Compatibility | Notes |
+| --- | --- | --- | --- |
+| ToHit | `HOOK_TOHIT` | ✅ | - |
+| AfterHitRoll | `HOOK_AFTERHITROLL` | 🚫 | Et tu |
+| CalcAPCost | `HOOK_CALCAPCOST` | 🚫 | - |
+| DeathAnim1 | `HOOK_DEATHANIM1` | 🚫 | Use DEATHANIM2 instead |
+| DeathAnim2 | `HOOK_DEATHANIM2` | ✅ | - |
+| CombatDamage | `HOOK_COMBATDAMAGE` | ✅ | - |
+| OnDeath | `HOOK_ONDEATH` | 🚫 | - |
+| FindTarget | `HOOK_FINDTARGET` | 🚫 | (maybe) |
+| UseObjOn | `HOOK_USEOBJON` | ✅ | - |
+| UseObj | `HOOK_USEOBJ` | ✅ | CE notes an sfall-matching inconsistency around return code `2` behavior between interface contexts. |
+| RemoveInvenObj | `HOOK_REMOVEINVENOBJ` | 🚫 | - |
+| BarterPrice | `HOOK_BARTERPRICE` | ✅ | - |
+| MoveCost | `HOOK_MOVECOST` | 🚫 | - |
+| ItemDamage | `HOOK_ITEMDAMAGE` | 🚫 | - |
+| AmmoCost | `HOOK_AMMOCOST` | 🚫 | Et tu |
+| KeyPress | `HOOK_KEYPRESS` | ✅ | Third hook arg is currently `0`; CE doesn't use VK codes. |
+| MouseClick | `HOOK_MOUSECLICK` | 🚫 | - |
+| UseSkill | `HOOK_USESKILL` | 🚫 | - |
+| Steal | `HOOK_STEAL` | 🚫 | Et tu |
+| WithinPerception | `HOOK_WITHINPERCEPTION` | 🚫 | Et tu |
+| InventoryMove | `HOOK_INVENTORYMOVE` | ✅ | - |
+| InvenWield | `HOOK_INVENWIELD` | 🚫 | - |
+| AdjustFID | `HOOK_ADJUSTFID` | 🚫 | - |
+| CombatTurn | `HOOK_COMBATTURN` | ✅ | - |
+| StdProcedure | `HOOK_STDPROCEDURE` | 🚫 | Et tu |
+| StdProcedureEnd | `HOOK_STDPROCEDURE_END` | 🚫 | - |
+| CarTravel | `HOOK_CARTRAVEL` | 🚫 | - |
+| SetGlobalVar | `HOOK_SETGLOBALVAR` | 🚫 | - |
+| RestTimer | `HOOK_RESTTIMER` | 🚫 | Et tu |
+| GameModeChange | `HOOK_GAMEMODECHANGE` | ✅ | - |
+| UseAnimObj | `HOOK_USEANIMOBJ` | 🚫 | Et tu; (maybe) |
+| ExplosiveTimer | `HOOK_EXPLOSIVETIMER` | 🚫 | - |
+| DescriptionObj | `HOOK_DESCRIPTIONOBJ` | 🚫 | Et tu |
+| UseSkillOn | `HOOK_USESKILLON` | 🚫 | Et tu |
+| OnExplosion | `HOOK_ONEXPLOSION` | 🚫 | (maybe) |
+| SubCombatDamage | `HOOK_SUBCOMBATDAMAGE` | 🚫 | (maybe) |
+| SetLighting | `HOOK_SETLIGHTING` | 🚫 | Et tu; (maybe) |
+| Sneak | `HOOK_SNEAK` | 🚫 | - |
+| TargetObject | `HOOK_TARGETOBJECT` | 🚫 | (maybe) |
+| Encounter | `HOOK_ENCOUNTER` | 🚫 | Et tu |
+| AdjustPoison | `HOOK_ADJUSTPOISON` | 🚫 | (maybe) |
+| AdjustRads | `HOOK_ADJUSTRADS` | 🚫 | (maybe) |
+| RollCheck | `HOOK_ROLLCHECK` | 🚫 | - |
+| BestWeapon | `HOOK_BESTWEAPON` | 🚫 | - |
+| CanUseWeapon | `HOOK_CANUSEWEAPON` | 🚫 | - |
+| BuildSfxWeapon | `HOOK_BUILDSFXWEAPON` | 🚫 | - |
@@ -197,11 +197,6 @@ NumbersInDialogue=0
 ;XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 [Scripts]

-;Comma-separated list of masked paths to load global scripts from
-;Only use single backslash \ as the directory separator
-;Paths outside of scripts folder are supported
-;GlobalScriptPaths=scripts\gl_*.int,scripts\sfall\gl*.int
-
 ;Uncomment the option to specify an additional directory for ini files used by scripts
 ;The game will search for ini files first relative to this directory and then relative to the root directory if not found
 ;The path length is limited to 61 characters
@@ -2,12 +2,97 @@ plugins {
    id 'com.android.application'
 }

+def sdlJavaBindingsDir = file('src/main/java/org/libsdl/app')
+
+def findFetchedSdlJavaBindingsDir = { String variantName ->
+    String variantCap = variantName.capitalize()
+    File intermediatesVariantDir = file("build/intermediates/cxx/${variantCap}")
+    if (!intermediatesVariantDir.isDirectory()) {
+        throw new GradleException("SDL sync check failed: missing active CXX intermediates under ${intermediatesVariantDir}. Run externalNativeBuild${variantCap} first.")
+    }
+
+    File[] activeHashDirs = intermediatesVariantDir.listFiles()
+    if (activeHashDirs == null) {
+        throw new GradleException("SDL sync check failed: could not list active CXX intermediates under ${intermediatesVariantDir}.")
+    }
+
+    activeHashDirs = activeHashDirs.findAll { it.isDirectory() }.sort { a, b -> a.name <=> b.name }
+    if (activeHashDirs.size() != 1) {
+        throw new GradleException(
+            "SDL sync check failed: expected exactly one active CXX hash directory under ${intermediatesVariantDir}, found ${activeHashDirs*.name}."
+        )
+    }
+
+    File fetchedDir = file(".cxx/${variantCap}/${activeHashDirs[0].name}/arm64-v8a/_deps/sdl2-src/android-project/app/src/main/java/org/libsdl/app")
+
+    if (!fetchedDir.isDirectory()) {
+        throw new GradleException("SDL sync check failed: could not locate fetched SDL Java bindings under ${fetchedDir}.")
+    }
+
+    return fetchedDir
+}
+
+def assertSdlJavaBindingsMatch = { String variantName ->
+    File fetchedDir = findFetchedSdlJavaBindingsDir(variantName)
+
+    if (!sdlJavaBindingsDir.isDirectory()) {
+        throw new GradleException("SDL sync check failed: committed SDL Java bindings directory is missing or unreadable: ${sdlJavaBindingsDir}.")
+    }
+
+    File[] committedFiles = sdlJavaBindingsDir.listFiles()
+    if (committedFiles == null) {
+        throw new GradleException("SDL sync check failed: could not list committed SDL Java bindings directory: ${sdlJavaBindingsDir}.")
+    }
+
+    File[] fetchedFiles = fetchedDir.listFiles()
+    if (fetchedFiles == null) {
+        throw new GradleException("SDL sync check failed: could not list fetched SDL Java bindings directory: ${fetchedDir}.")
+    }
+
+    Set<String> committedNames = committedFiles
+        .findAll { it.isFile() && it.name.endsWith('.java') }
+        .collect { it.name }
+        .toSet()
+    Set<String> fetchedNames = fetchedFiles
+        .findAll { it.isFile() && it.name.endsWith('.java') }
+        .collect { it.name }
+        .toSet()
+
+    Set<String> missingFromCommitted = fetchedNames - committedNames
+    Set<String> extraInCommitted = committedNames - fetchedNames
+
+    if (!missingFromCommitted.isEmpty() || !extraInCommitted.isEmpty()) {
+        throw new GradleException(
+            "SDL Android Java bindings are out of sync with native SDL for ${variantName}.\n" +
+            "Fetched SDL dir: ${fetchedDir}\n" +
+            "Missing from committed bindings: ${missingFromCommitted.sort()}\n" +
+            "Extra committed bindings: ${extraInCommitted.sort()}\n" +
+            "Sync os/android/app/src/main/java/org/libsdl/app from the fetched SDL android-project sources."
+        )
+    }
+
+    List<String> changedFiles = committedNames.findAll { fileName ->
+        File committedFile = new File(sdlJavaBindingsDir, fileName)
+        File fetchedFile = new File(fetchedDir, fileName)
+        committedFile.getText('UTF-8') != fetchedFile.getText('UTF-8')
+    }.sort()
+
+    if (!changedFiles.isEmpty()) {
+        throw new GradleException(
+            "SDL Android Java bindings are out of sync with native SDL for ${variantName}.\n" +
+            "Fetched SDL dir: ${fetchedDir}\n" +
+            "Changed files: ${changedFiles}\n" +
+            "Sync os/android/app/src/main/java/org/libsdl/app from the fetched SDL android-project sources."
+        )
+    }
+}
+
 android {
    compileSdk 32

    defaultConfig {
        applicationId 'com.alexbatalov.fallout2ce'
-        minSdk 21
+        minSdk 24
        targetSdk 32
        versionCode 4
        versionName '1.3.0'
@@ -78,8 +163,20 @@ android {
    }

    applicationVariants.all { variant ->
-        tasks["merge${variant.name.capitalize()}Assets"]
-            .dependsOn("externalNativeBuild${variant.name.capitalize()}")
+        String variantCap = variant.name.capitalize()
+        String syncCheckTaskName = "checkSdlJavaBindingsSync${variantCap}"
+
+        if (!project.hasProperty('EXCLUDE_NATIVE_LIBS')) {
+            tasks.register(syncCheckTaskName) {
+                dependsOn("externalNativeBuild${variantCap}")
+                doLast {
+                    assertSdlJavaBindingsMatch(variant.name)
+                }
+            }
+
+            tasks["merge${variantCap}Assets"]
+                .dependsOn(syncCheckTaskName)
+        }
    }

    if (!project.hasProperty('EXCLUDE_NATIVE_LIBS')) {
@@ -186,7 +186,7 @@ class HIDDeviceBLESteamController extends BluetoothGattCallback implements HIDDe
    // Because on Chromebooks we show up as a dual-mode device, it will attempt to connect TRANSPORT_AUTO, which will use TRANSPORT_BREDR instead
    // of TRANSPORT_LE.  Let's force ourselves to connect low energy.
    private BluetoothGatt connectGatt(boolean managed) {
-        if (Build.VERSION.SDK_INT >= 23) {
+        if (Build.VERSION.SDK_INT >= 23 /* Android 6.0 (M) */) {
            try {
                return mDevice.connectGatt(mManager.getContext(), managed, this, TRANSPORT_LE);
            } catch (Exception e) {
@@ -429,7 +429,7 @@ class HIDDeviceBLESteamController extends BluetoothGattCallback implements HIDDe
                    }
                });
            }
-        } 
+        }
        else if (newState == 0) {
            mIsConnected = false;
        }
@@ -170,7 +170,7 @@ public class HIDDeviceManager {
                Log.i(TAG,"  Interface protocol: " + mUsbInterface.getInterfaceProtocol());
                Log.i(TAG,"  Endpoint count: " + mUsbInterface.getEndpointCount());

-                // Get endpoint details 
+                // Get endpoint details
                for (int epi = 0; epi < mUsbInterface.getEndpointCount(); epi++)
                {
                    UsbEndpoint mEndpoint = mUsbInterface.getEndpoint(epi);
@@ -251,6 +251,8 @@ public class HIDDeviceManager {
            0x20d6, // PowerA
            0x24c6, // PowerA
            0x2c22, // Qanba
+            0x2dc8, // 8BitDo
+            0x9886, // ASTRO Gaming
        };

        if (usbInterface.getInterfaceClass() == UsbConstants.USB_CLASS_VENDOR_SPEC &&
@@ -271,15 +273,20 @@ public class HIDDeviceManager {
        final int XB1_IFACE_SUBCLASS = 71;
        final int XB1_IFACE_PROTOCOL = 208;
        final int[] SUPPORTED_VENDORS = {
+            0x03f0, // HP
+            0x044f, // Thrustmaster
            0x045e, // Microsoft
            0x0738, // Mad Catz
+            0x0b05, // ASUS
            0x0e6f, // PDP
            0x0f0d, // Hori
+            0x10f5, // Turtle Beach
            0x1532, // Razer Wildcat
            0x20d6, // PowerA
            0x24c6, // PowerA
-            0x2dc8, /* 8BitDo */
+            0x2dc8, // 8BitDo
            0x2e24, // Hyperkin
+            0x3537, // GameSir
        };

        if (usbInterface.getId() == 0 &&
@@ -353,13 +360,19 @@ public class HIDDeviceManager {
    private void initializeBluetooth() {
        Log.d(TAG, "Initializing Bluetooth");

-        if (Build.VERSION.SDK_INT <= 30 &&
+        if (Build.VERSION.SDK_INT >= 31 /* Android 12  */ &&
+            mContext.getPackageManager().checkPermission(android.Manifest.permission.BLUETOOTH_CONNECT, mContext.getPackageName()) != PackageManager.PERMISSION_GRANTED) {
+            Log.d(TAG, "Couldn't initialize Bluetooth, missing android.permission.BLUETOOTH_CONNECT");
+            return;
+        }
+
+        if (Build.VERSION.SDK_INT <= 30 /* Android 11.0 (R) */ &&
            mContext.getPackageManager().checkPermission(android.Manifest.permission.BLUETOOTH, mContext.getPackageName()) != PackageManager.PERMISSION_GRANTED) {
            Log.d(TAG, "Couldn't initialize Bluetooth, missing android.permission.BLUETOOTH");
            return;
        }

-        if (!mContext.getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE) || (Build.VERSION.SDK_INT < 18)) {
+        if (!mContext.getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE) || (Build.VERSION.SDK_INT < 18 /* Android 4.3 (JELLY_BEAN_MR2) */)) {
            Log.d(TAG, "Couldn't initialize Bluetooth, this version of Android does not support Bluetooth LE");
            return;
        }
@@ -524,7 +537,7 @@ public class HIDDeviceManager {
            for (HIDDevice device : mDevicesById.values()) {
                device.setFrozen(frozen);
            }
-        }        
+        }
    }

    //////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -573,12 +586,18 @@ public class HIDDeviceManager {
            try {
                final int FLAG_MUTABLE = 0x02000000; // PendingIntent.FLAG_MUTABLE, but don't require SDK 31
                int flags;
-                if (Build.VERSION.SDK_INT >= 31) {
+                if (Build.VERSION.SDK_INT >= 31 /* Android 12.0 (S) */) {
                    flags = FLAG_MUTABLE;
                } else {
                    flags = 0;
                }
-                mUsbManager.requestPermission(usbDevice, PendingIntent.getBroadcast(mContext, 0, new Intent(HIDDeviceManager.ACTION_USB_PERMISSION), flags));
+                if (Build.VERSION.SDK_INT >= 33 /* Android 14.0 (U) */) {
+                   Intent intent = new Intent(HIDDeviceManager.ACTION_USB_PERMISSION);
+                   intent.setPackage(mContext.getPackageName());
+                   mUsbManager.requestPermission(usbDevice, PendingIntent.getBroadcast(mContext, 0, intent, flags));
+               } else {
+                   mUsbManager.requestPermission(usbDevice, PendingIntent.getBroadcast(mContext, 0, new Intent(HIDDeviceManager.ACTION_USB_PERMISSION), flags));
+               }
            } catch (Exception e) {
                Log.v(TAG, "Couldn't request permission for USB device " + usbDevice);
                HIDDeviceOpenResult(deviceID, false);
@@ -52,7 +52,7 @@ class HIDDeviceUSB implements HIDDevice {
    @Override
    public String getSerialNumber() {
        String result = null;
-        if (Build.VERSION.SDK_INT >= 21) {
+        if (Build.VERSION.SDK_INT >= 21 /* Android 5.0 (LOLLIPOP) */) {
            try {
                result = mDevice.getSerialNumber();
            }
@@ -74,7 +74,7 @@ class HIDDeviceUSB implements HIDDevice {
    @Override
    public String getManufacturerName() {
        String result = null;
-        if (Build.VERSION.SDK_INT >= 21) {
+        if (Build.VERSION.SDK_INT >= 21 /* Android 5.0 (LOLLIPOP) */) {
            result = mDevice.getManufacturerName();
        }
        if (result == null) {
@@ -86,7 +86,7 @@ class HIDDeviceUSB implements HIDDevice {
    @Override
    public String getProductName() {
        String result = null;
-        if (Build.VERSION.SDK_INT >= 21) {
+        if (Build.VERSION.SDK_INT >= 21 /* Android 5.0 (LOLLIPOP) */) {
            result = mDevice.getProductName();
        }
        if (result == null) {
@@ -29,6 +29,7 @@ public class SDL {

    // This function stores the current activity (SDL or not)
    public static void setContext(Context context) {
+        SDLAudioManager.setContext(context);
        mContext = context;
    }

@@ -37,6 +38,10 @@ public class SDL {
    }

    public static void loadLibrary(String libraryName) throws UnsatisfiedLinkError, SecurityException, NullPointerException {
+        loadLibrary(libraryName, mContext);
+    }
+
+    public static void loadLibrary(String libraryName, Context context) throws UnsatisfiedLinkError, SecurityException, NullPointerException {

        if (libraryName == null) {
            throw new NullPointerException("No library name provided.");
@@ -52,10 +57,10 @@ public class SDL {
            // To use ReLinker, just add it as a dependency.  For more information, see 
            // https://github.com/KeepSafe/ReLinker for ReLinker's repository.
            //
-            Class<?> relinkClass = mContext.getClassLoader().loadClass("com.getkeepsafe.relinker.ReLinker");
-            Class<?> relinkListenerClass = mContext.getClassLoader().loadClass("com.getkeepsafe.relinker.ReLinker$LoadListener");
-            Class<?> contextClass = mContext.getClassLoader().loadClass("android.content.Context");
-            Class<?> stringClass = mContext.getClassLoader().loadClass("java.lang.String");
+            Class<?> relinkClass = context.getClassLoader().loadClass("com.getkeepsafe.relinker.ReLinker");
+            Class<?> relinkListenerClass = context.getClassLoader().loadClass("com.getkeepsafe.relinker.ReLinker$LoadListener");
+            Class<?> contextClass = context.getClassLoader().loadClass("android.content.Context");
+            Class<?> stringClass = context.getClassLoader().loadClass("java.lang.String");

            // Get a 'force' instance of the ReLinker, so we can ensure libraries are reinstalled if 
            // they've changed during updates.
@@ -65,7 +70,7 @@ public class SDL {

            // Actually load the library!
            Method loadMethod = relinkInstanceClass.getDeclaredMethod("loadLibrary", contextClass, stringClass, stringClass, relinkListenerClass);
-            loadMethod.invoke(relinkInstance, mContext, libraryName, null, null);
+            loadMethod.invoke(relinkInstance, context, libraryName, null, null);
        }
        catch (final Throwable e) {
            // Fall back
@@ -60,8 +60,8 @@ import java.util.Locale;
 public class SDLActivity extends Activity implements View.OnSystemUiVisibilityChangeListener {
    private static final String TAG = "SDL";
    private static final int SDL_MAJOR_VERSION = 2;
-    private static final int SDL_MINOR_VERSION = 26;
-    private static final int SDL_MICRO_VERSION = 1;
+    private static final int SDL_MINOR_VERSION = 32;
+    private static final int SDL_MICRO_VERSION = 8;
 /*
    // Display InputType.SOURCE/CLASS of events and devices
    //
@@ -89,11 +89,11 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
                | InputDevice.SOURCE_CLASS_POSITION
                | InputDevice.SOURCE_CLASS_TRACKBALL);

-        if (s2 != 0) cls += "Some_Unkown";
+        if (s2 != 0) cls += "Some_Unknown";

        s2 = s_copy & InputDevice.SOURCE_ANY; // keep source only, no class;

-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+        if (Build.VERSION.SDK_INT >= 23) {
            tst = InputDevice.SOURCE_BLUETOOTH_STYLUS;
            if ((s & tst) == tst) src += " BLUETOOTH_STYLUS";
            s2 &= ~tst;
@@ -107,7 +107,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        if ((s & tst) == tst) src += " GAMEPAD";
        s2 &= ~tst;

-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
+        if (Build.VERSION.SDK_INT >= 21) {
            tst = InputDevice.SOURCE_HDMI;
            if ((s & tst) == tst) src += " HDMI";
            s2 &= ~tst;
@@ -146,7 +146,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        if ((s & tst) == tst) src += " TOUCHSCREEN";
        s2 &= ~tst;

-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR2) {
+        if (Build.VERSION.SDK_INT >= 18) {
            tst = InputDevice.SOURCE_TOUCH_NAVIGATION;
            if ((s & tst) == tst) src += " TOUCH_NAVIGATION";
            s2 &= ~tst;
@@ -163,14 +163,14 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        if (s == FLAG_TAINTED) src += " FLAG_TAINTED";
        s2 &= ~FLAG_TAINTED;

-        if (s2 != 0) src += " Some_Unkown";
+        if (s2 != 0) src += " Some_Unknown";

        Log.v(TAG, prefix + "int=" + s_copy + " CLASS={" + cls + " } source(s):" + src);
    }
 */

    public static boolean mIsResumedCalled, mHasFocus;
-    public static final boolean mHasMultiWindow = (Build.VERSION.SDK_INT >= 24);
+    public static final boolean mHasMultiWindow = (Build.VERSION.SDK_INT >= 24  /* Android 7.0 (N) */);

    // Cursor types
    // private static final int SDL_SYSTEM_CURSOR_NONE = -1;
@@ -224,9 +224,9 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh

    protected static SDLGenericMotionListener_API12 getMotionListener() {
        if (mMotionListener == null) {
-            if (Build.VERSION.SDK_INT >= 26) {
+            if (Build.VERSION.SDK_INT >= 26 /* Android 8.0 (O) */) {
                mMotionListener = new SDLGenericMotionListener_API26();
-            } else if (Build.VERSION.SDK_INT >= 24) {
+            } else if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
                mMotionListener = new SDLGenericMotionListener_API24();
            } else {
                mMotionListener = new SDLGenericMotionListener_API12();
@@ -281,7 +281,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
    // Load the .so
    public void loadLibraries() {
       for (String lib : getLibraries()) {
-          SDL.loadLibrary(lib);
+          SDL.loadLibrary(lib, this);
       }
    }

@@ -393,7 +393,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        mHIDDeviceManager = HIDDeviceManager.acquire(this);

        // Set up the surface
-        mSurface = createSDLSurface(getApplication());
+        mSurface = createSDLSurface(this);

        mLayout = new RelativeLayout(this);
        mLayout.addView(mSurface);
@@ -404,7 +404,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        SDLActivity.onNativeOrientationChanged(mCurrentOrientation);

        try {
-            if (Build.VERSION.SDK_INT < 24) {
+            if (Build.VERSION.SDK_INT < 24 /* Android 7.0 (N) */) {
                mCurrentLocale = getContext().getResources().getConfiguration().locale;
            } else {
                mCurrentLocale = getContext().getResources().getConfiguration().getLocales().get(0);
@@ -588,6 +588,8 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
            mHIDDeviceManager = null;
        }

+        SDLAudioManager.release(this);
+
        if (SDLActivity.mBrokenLibraries) {
           super.onDestroy();
           return;
@@ -766,7 +768,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
                }
                break;
            case COMMAND_CHANGE_WINDOW_STYLE:
-                if (Build.VERSION.SDK_INT >= 19) {
+                if (Build.VERSION.SDK_INT >= 19 /* Android 4.4 (KITKAT) */) {
                    if (context instanceof Activity) {
                        Window window = ((Activity) context).getWindow();
                        if (window != null) {
@@ -788,6 +790,9 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
                                window.clearFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN);
                                SDLActivity.mFullscreenModeActive = false;
                            }
+                            if (Build.VERSION.SDK_INT >= 28 /* Android 9 (Pie) */) {
+                                window.getAttributes().layoutInDisplayCutoutMode = WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES;
+                            }
                        }
                    } else {
                        Log.e(TAG, "error handling message, getContext() returned no Activity");
@@ -841,7 +846,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        msg.obj = data;
        boolean result = commandHandler.sendMessage(msg);

-        if (Build.VERSION.SDK_INT >= 19) {
+        if (Build.VERSION.SDK_INT >= 19 /* Android 4.4 (KITKAT) */) {
            if (command == COMMAND_CHANGE_WINDOW_STYLE) {
                // Ensure we don't return until the resize has actually happened,
                // or 500ms have passed.
@@ -969,15 +974,18 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        /* If set, hint "explicitly controls which UI orientations are allowed". */
        if (hint.contains("LandscapeRight") && hint.contains("LandscapeLeft")) {
            orientation_landscape = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE;
-        } else if (hint.contains("LandscapeRight")) {
-            orientation_landscape = ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE;
        } else if (hint.contains("LandscapeLeft")) {
+            orientation_landscape = ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE;
+        } else if (hint.contains("LandscapeRight")) {
            orientation_landscape = ActivityInfo.SCREEN_ORIENTATION_REVERSE_LANDSCAPE;
        }

-        if (hint.contains("Portrait") && hint.contains("PortraitUpsideDown")) {
+        /* exact match to 'Portrait' to distinguish with PortraitUpsideDown */
+        boolean contains_Portrait = hint.contains("Portrait ") || hint.endsWith("Portrait");
+
+        if (contains_Portrait && hint.contains("PortraitUpsideDown")) {
            orientation_portrait = ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT;
-        } else if (hint.contains("Portrait")) {
+        } else if (contains_Portrait) {
            orientation_portrait = ActivityInfo.SCREEN_ORIENTATION_PORTRAIT;
        } else if (hint.contains("PortraitUpsideDown")) {
            orientation_portrait = ActivityInfo.SCREEN_ORIENTATION_REVERSE_PORTRAIT;
@@ -990,8 +998,8 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        /* No valid hint, nothing is explicitly allowed */
        if (!is_portrait_allowed && !is_landscape_allowed) {
            if (resizable) {
-                /* All orientations are allowed */
-                req = ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR;
+                /* All orientations are allowed, respecting user orientation lock setting */
+                req = ActivityInfo.SCREEN_ORIENTATION_FULL_USER;
            } else {
                /* Fixed window and nothing specified. Get orientation from w/h of created window */
                req = (w > h ? ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE : ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT);
@@ -1000,8 +1008,8 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
            /* At least one orientation is allowed */
            if (resizable) {
                if (is_portrait_allowed && is_landscape_allowed) {
-                    /* hint allows both landscape and portrait, promote to full sensor */
-                    req = ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR;
+                    /* hint allows both landscape and portrait, promote to full user */
+                    req = ActivityInfo.SCREEN_ORIENTATION_FULL_USER;
                } else {
                    /* Use the only one allowed "orientation" */
                    req = (is_landscape_allowed ? orientation_landscape : orientation_portrait);
@@ -1090,7 +1098,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        // thus SDK version 27.  If we are in DeX mode and not API 27 or higher, as a result,
        // we should stick to relative mode.
        //
-        if ((Build.VERSION.SDK_INT < 27) && isDeXMode()) {
+        if (Build.VERSION.SDK_INT < 27 /* Android 8.1 (O_MR1) */ && isDeXMode()) {
            return false;
        }

@@ -1180,7 +1188,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
     * This method is called by SDL using JNI.
     */
    public static boolean isDeXMode() {
-        if (Build.VERSION.SDK_INT < 24) {
+        if (Build.VERSION.SDK_INT < 24 /* Android 7.0 (N) */) {
            return false;
        }
        try {
@@ -1340,23 +1348,6 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
            }
        }

-        if ((source & InputDevice.SOURCE_KEYBOARD) == InputDevice.SOURCE_KEYBOARD) {
-            if (event.getAction() == KeyEvent.ACTION_DOWN) {
-                if (isTextInputEvent(event)) {
-                    if (ic != null) {
-                        ic.commitText(String.valueOf((char) event.getUnicodeChar()), 1);
-                    } else {
-                        SDLInputConnection.nativeCommitText(String.valueOf((char) event.getUnicodeChar()), 1);
-                    }
-                }
-                onNativeKeyDown(keyCode);
-                return true;
-            } else if (event.getAction() == KeyEvent.ACTION_UP) {
-                onNativeKeyUp(keyCode);
-                return true;
-            }
-        }
-
        if ((source & InputDevice.SOURCE_MOUSE) == InputDevice.SOURCE_MOUSE) {
            // on some devices key events are sent for mouse BUTTON_BACK/FORWARD presses
            // they are ignored here because sending them as mouse input to SDL is messy
@@ -1371,6 +1362,21 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
            }
        }

+        if (event.getAction() == KeyEvent.ACTION_DOWN) {
+            if (isTextInputEvent(event)) {
+                if (ic != null) {
+                    ic.commitText(String.valueOf((char) event.getUnicodeChar()), 1);
+                } else {
+                    SDLInputConnection.nativeCommitText(String.valueOf((char) event.getUnicodeChar()), 1);
+                }
+            }
+            onNativeKeyDown(keyCode);
+            return true;
+        } else if (event.getAction() == KeyEvent.ACTION_UP) {
+            onNativeKeyUp(keyCode);
+            return true;
+        }
+
        return false;
    }

@@ -1617,7 +1623,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
    private final Runnable rehideSystemUi = new Runnable() {
        @Override
        public void run() {
-            if (Build.VERSION.SDK_INT >= 19) {
+            if (Build.VERSION.SDK_INT >= 19 /* Android 4.4 (KITKAT) */) {
                int flags = View.SYSTEM_UI_FLAG_FULLSCREEN |
                        View.SYSTEM_UI_FLAG_HIDE_NAVIGATION |
                        View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY |
@@ -1670,7 +1676,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
        Bitmap bitmap = Bitmap.createBitmap(colors, width, height, Bitmap.Config.ARGB_8888);
        ++mLastCursorID;

-        if (Build.VERSION.SDK_INT >= 24) {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
            try {
                mCursors.put(mLastCursorID, PointerIcon.create(bitmap, hotSpotX, hotSpotY));
            } catch (Exception e) {
@@ -1686,7 +1692,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
     * This method is called by SDL using JNI.
     */
    public static void destroyCustomCursor(int cursorID) {
-        if (Build.VERSION.SDK_INT >= 24) {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
            try {
                mCursors.remove(cursorID);
            } catch (Exception e) {
@@ -1700,7 +1706,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
     */
    public static boolean setCustomCursor(int cursorID) {

-        if (Build.VERSION.SDK_INT >= 24) {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
            try {
                mSurface.setPointerIcon(mCursors.get(cursorID));
            } catch (Exception e) {
@@ -1755,7 +1761,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
            cursor_type = 1002; //PointerIcon.TYPE_HAND;
            break;
        }
-        if (Build.VERSION.SDK_INT >= 24) {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
            try {
                mSurface.setPointerIcon(PointerIcon.getSystemIcon(SDL.getContext(), cursor_type));
            } catch (Exception e) {
@@ -1769,7 +1775,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
     * This method is called by SDL using JNI.
     */
    public static void requestPermission(String permission, int requestCode) {
-        if (Build.VERSION.SDK_INT < 23) {
+        if (Build.VERSION.SDK_INT < 23 /* Android 6.0 (M) */) {
            nativePermissionResult(requestCode, true);
            return;
        }
@@ -1798,7 +1804,7 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityCh
            i.setData(Uri.parse(url));

            int flags = Intent.FLAG_ACTIVITY_NO_HISTORY | Intent.FLAG_ACTIVITY_MULTIPLE_TASK;
-            if (Build.VERSION.SDK_INT >= 21) {
+            if (Build.VERSION.SDK_INT >= 21 /* Android 5.0 (LOLLIPOP) */) {
                flags |= Intent.FLAG_ACTIVITY_NEW_DOCUMENT;
            } else {
                flags |= Intent.FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET;
@@ -2002,6 +2008,18 @@ class SDLInputConnection extends BaseInputConnection {

    @Override
    public boolean deleteSurroundingText(int beforeLength, int afterLength) {
+        if (Build.VERSION.SDK_INT <= 29 /* Android 10.0 (Q) */) {
+            // Workaround to capture backspace key. Ref: http://stackoverflow.com/questions>/14560344/android-backspace-in-webview-baseinputconnection
+            // and https://bugzilla.libsdl.org/show_bug.cgi?id=2265
+            if (beforeLength > 0 && afterLength == 0) {
+                // backspace(s)
+                while (beforeLength-- > 0) {
+                    nativeGenerateScancodeForUnichar('\b');
+                }
+                return true;
+           }
+        }
+
        if (!super.deleteSurroundingText(beforeLength, afterLength)) {
            return false;
        }
@@ -1,5 +1,8 @@
 package org.libsdl.app;

+import android.content.Context;
+import android.media.AudioDeviceCallback;
+import android.media.AudioDeviceInfo;
 import android.media.AudioFormat;
 import android.media.AudioManager;
 import android.media.AudioRecord;
@@ -8,34 +11,67 @@ import android.media.MediaRecorder;
 import android.os.Build;
 import android.util.Log;

-public class SDLAudioManager
-{
+import java.util.Arrays;
+
+public class SDLAudioManager {
    protected static final String TAG = "SDLAudio";

    protected static AudioTrack mAudioTrack;
    protected static AudioRecord mAudioRecord;
+    protected static Context mContext;
+
+    private static final int[] NO_DEVICES = {};
+
+    private static AudioDeviceCallback mAudioDeviceCallback;

    public static void initialize() {
        mAudioTrack = null;
        mAudioRecord = null;
+        mAudioDeviceCallback = null;
+
+        if(Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */)
+        {
+            mAudioDeviceCallback = new AudioDeviceCallback() {
+                @Override
+                public void onAudioDevicesAdded(AudioDeviceInfo[] addedDevices) {
+                    Arrays.stream(addedDevices).forEach(deviceInfo -> addAudioDevice(deviceInfo.isSink(), deviceInfo.getId()));
+                }
+
+                @Override
+                public void onAudioDevicesRemoved(AudioDeviceInfo[] removedDevices) {
+                    Arrays.stream(removedDevices).forEach(deviceInfo -> removeAudioDevice(deviceInfo.isSink(), deviceInfo.getId()));
+                }
+            };
+        }
+    }
+
+    public static void setContext(Context context) {
+        mContext = context;
+        if (context != null) {
+            registerAudioDeviceCallback();
+        }
+    }
+
+    public static void release(Context context) {
+        unregisterAudioDeviceCallback(context);
    }

    // Audio

    protected static String getAudioFormatString(int audioFormat) {
        switch (audioFormat) {
-        case AudioFormat.ENCODING_PCM_8BIT:
-            return "8-bit";
-        case AudioFormat.ENCODING_PCM_16BIT:
-            return "16-bit";
-        case AudioFormat.ENCODING_PCM_FLOAT:
-            return "float";
-        default:
-            return Integer.toString(audioFormat);
+            case AudioFormat.ENCODING_PCM_8BIT:
+                return "8-bit";
+            case AudioFormat.ENCODING_PCM_16BIT:
+                return "16-bit";
+            case AudioFormat.ENCODING_PCM_FLOAT:
+                return "float";
+            default:
+                return Integer.toString(audioFormat);
        }
    }

-    protected static int[] open(boolean isCapture, int sampleRate, int audioFormat, int desiredChannels, int desiredFrames) {
+    protected static int[] open(boolean isCapture, int sampleRate, int audioFormat, int desiredChannels, int desiredFrames, int deviceId) {
        int channelConfig;
        int sampleSize;
        int frameSize;
@@ -43,14 +79,14 @@ public class SDLAudioManager
        Log.v(TAG, "Opening " + (isCapture ? "capture" : "playback") + ", requested " + desiredFrames + " frames of " + desiredChannels + " channel " + getAudioFormatString(audioFormat) + " audio at " + sampleRate + " Hz");

        /* On older devices let's use known good settings */
-        if (Build.VERSION.SDK_INT < 21) {
+        if (Build.VERSION.SDK_INT < 21 /* Android 5.0 (LOLLIPOP) */) {
            if (desiredChannels > 2) {
                desiredChannels = 2;
            }
        }

        /* AudioTrack has sample rate limitation of 48000 (fixed in 5.0.2) */
-        if (Build.VERSION.SDK_INT < 22) {
+        if (Build.VERSION.SDK_INT < 22 /* Android 5.1 (LOLLIPOP_MR1) */) {
            if (sampleRate < 8000) {
                sampleRate = 8000;
            } else if (sampleRate > 48000) {
@@ -59,7 +95,7 @@ public class SDLAudioManager
        }

        if (audioFormat == AudioFormat.ENCODING_PCM_FLOAT) {
-            int minSDKVersion = (isCapture ? 23 : 21);
+            int minSDKVersion = (isCapture ? 23 /* Android 6.0 (M) */ : 21 /* Android 5.0 (LOLLIPOP) */);
            if (Build.VERSION.SDK_INT < minSDKVersion) {
                audioFormat = AudioFormat.ENCODING_PCM_16BIT;
            }
@@ -120,7 +156,7 @@ public class SDLAudioManager
                channelConfig = AudioFormat.CHANNEL_OUT_5POINT1 | AudioFormat.CHANNEL_OUT_BACK_CENTER;
                break;
            case 8:
-                if (Build.VERSION.SDK_INT >= 23) {
+                if (Build.VERSION.SDK_INT >= 23 /* Android 6.0 (M) */) {
                    channelConfig = AudioFormat.CHANNEL_OUT_7POINT1_SURROUND;
                } else {
                    Log.v(TAG, "Requested " + desiredChannels + " channels, getting 5.1 surround");
@@ -201,6 +237,10 @@ public class SDLAudioManager
                    return null;
                }

+                if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */ && deviceId != 0) {
+                    mAudioRecord.setPreferredDevice(getOutputAudioDeviceInfo(deviceId));
+                }
+
                mAudioRecord.startRecording();
            }

@@ -224,6 +264,10 @@ public class SDLAudioManager
                    return null;
                }

+                if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */ && deviceId != 0) {
+                    mAudioTrack.setPreferredDevice(getInputAudioDeviceInfo(deviceId));
+                }
+
                mAudioTrack.play();
            }

@@ -238,11 +282,73 @@ public class SDLAudioManager
        return results;
    }

+    private static AudioDeviceInfo getInputAudioDeviceInfo(int deviceId) {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
+            AudioManager audioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
+            return Arrays.stream(audioManager.getDevices(AudioManager.GET_DEVICES_INPUTS))
+                    .filter(deviceInfo -> deviceInfo.getId() == deviceId)
+                    .findFirst()
+                    .orElse(null);
+        } else {
+            return null;
+        }
+    }
+
+    private static AudioDeviceInfo getOutputAudioDeviceInfo(int deviceId) {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
+            AudioManager audioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
+            return Arrays.stream(audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS))
+                    .filter(deviceInfo -> deviceInfo.getId() == deviceId)
+                    .findFirst()
+                    .orElse(null);
+        } else {
+            return null;
+        }
+    }
+
+    private static void registerAudioDeviceCallback() {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
+            AudioManager audioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
+            audioManager.registerAudioDeviceCallback(mAudioDeviceCallback, null);
+        }
+    }
+
+    private static void unregisterAudioDeviceCallback(Context context) {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
+            AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
+            audioManager.unregisterAudioDeviceCallback(mAudioDeviceCallback);
+        }
+    }
+
    /**
     * This method is called by SDL using JNI.
     */
-    public static int[] audioOpen(int sampleRate, int audioFormat, int desiredChannels, int desiredFrames) {
-        return open(false, sampleRate, audioFormat, desiredChannels, desiredFrames);
+    public static int[] getAudioOutputDevices() {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
+            AudioManager audioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
+            return Arrays.stream(audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)).mapToInt(AudioDeviceInfo::getId).toArray();
+        } else {
+            return NO_DEVICES;
+        }
+    }
+
+    /**
+     * This method is called by SDL using JNI.
+     */
+    public static int[] getAudioInputDevices() {
+        if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
+            AudioManager audioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
+            return Arrays.stream(audioManager.getDevices(AudioManager.GET_DEVICES_INPUTS)).mapToInt(AudioDeviceInfo::getId).toArray();
+        } else {
+            return NO_DEVICES;
+        }
+    }
+
+    /**
+     * This method is called by SDL using JNI.
+     */
+    public static int[] audioOpen(int sampleRate, int audioFormat, int desiredChannels, int desiredFrames, int deviceId) {
+        return open(false, sampleRate, audioFormat, desiredChannels, desiredFrames, deviceId);
    }

    /**
@@ -254,6 +360,11 @@ public class SDLAudioManager
            return;
        }

+        if (android.os.Build.VERSION.SDK_INT < 21 /* Android 5.0 (LOLLIPOP) */) {
+            Log.e(TAG, "Attempted to make an incompatible audio call with uninitialized audio! (floating-point output is supported since Android 5.0 Lollipop)");
+            return;
+        }
+
        for (int i = 0; i < buffer.length;) {
            int result = mAudioTrack.write(buffer, i, buffer.length - i, AudioTrack.WRITE_BLOCKING);
            if (result > 0) {
@@ -326,18 +437,22 @@ public class SDLAudioManager
    /**
     * This method is called by SDL using JNI.
     */
-    public static int[] captureOpen(int sampleRate, int audioFormat, int desiredChannels, int desiredFrames) {
-        return open(true, sampleRate, audioFormat, desiredChannels, desiredFrames);
+    public static int[] captureOpen(int sampleRate, int audioFormat, int desiredChannels, int desiredFrames, int deviceId) {
+        return open(true, sampleRate, audioFormat, desiredChannels, desiredFrames, deviceId);
    }

    /** This method is called by SDL using JNI. */
    public static int captureReadFloatBuffer(float[] buffer, boolean blocking) {
-        return mAudioRecord.read(buffer, 0, buffer.length, blocking ? AudioRecord.READ_BLOCKING : AudioRecord.READ_NON_BLOCKING);
+        if (Build.VERSION.SDK_INT < 23 /* Android 6.0 (M) */) {
+            return 0;
+        } else {
+            return mAudioRecord.read(buffer, 0, buffer.length, blocking ? AudioRecord.READ_BLOCKING : AudioRecord.READ_NON_BLOCKING);
+        }
    }

    /** This method is called by SDL using JNI. */
    public static int captureReadShortBuffer(short[] buffer, boolean blocking) {
-        if (Build.VERSION.SDK_INT < 23) {
+        if (Build.VERSION.SDK_INT < 23 /* Android 6.0 (M) */) {
            return mAudioRecord.read(buffer, 0, buffer.length);
        } else {
            return mAudioRecord.read(buffer, 0, buffer.length, blocking ? AudioRecord.READ_BLOCKING : AudioRecord.READ_NON_BLOCKING);
@@ -346,7 +461,7 @@ public class SDLAudioManager

    /** This method is called by SDL using JNI. */
    public static int captureReadByteBuffer(byte[] buffer, boolean blocking) {
-        if (Build.VERSION.SDK_INT < 23) {
+        if (Build.VERSION.SDK_INT < 23 /* Android 6.0 (M) */) {
            return mAudioRecord.read(buffer, 0, buffer.length);
        } else {
            return mAudioRecord.read(buffer, 0, buffer.length, blocking ? AudioRecord.READ_BLOCKING : AudioRecord.READ_NON_BLOCKING);
@@ -391,4 +506,9 @@ public class SDLAudioManager
    }

    public static native int nativeSetupJNI();
+
+    public static native void removeAudioDevice(boolean isCapture, int deviceId);
+
+    public static native void addAudioDevice(boolean isCapture, int deviceId);
+
 }
@@ -24,7 +24,7 @@ public class SDLControllerManager
    public static native int nativeAddJoystick(int device_id, String name, String desc,
                                               int vendor_id, int product_id,
                                               boolean is_accelerometer, int button_mask,
-                                               int naxes, int nhats, int nballs);
+                                               int naxes, int axis_mask, int nhats, int nballs);
    public static native int nativeRemoveJoystick(int device_id);
    public static native int nativeAddHaptic(int device_id, String name);
    public static native int nativeRemoveHaptic(int device_id);
@@ -42,7 +42,7 @@ public class SDLControllerManager

    public static void initialize() {
        if (mJoystickHandler == null) {
-            if (Build.VERSION.SDK_INT >= 19) {
+            if (Build.VERSION.SDK_INT >= 19 /* Android 4.4 (KITKAT) */) {
                mJoystickHandler = new SDLJoystickHandler_API19();
            } else {
                mJoystickHandler = new SDLJoystickHandler_API16();
@@ -50,7 +50,7 @@ public class SDLControllerManager
        }

        if (mHapticHandler == null) {
-            if (Build.VERSION.SDK_INT >= 26) {
+            if (Build.VERSION.SDK_INT >= 26 /* Android 8.0 (O) */) {
                mHapticHandler = new SDLHapticHandler_API26();
            } else {
                mHapticHandler = new SDLHapticHandler();
@@ -168,6 +168,32 @@ class SDLJoystickHandler_API16 extends SDLJoystickHandler {
                arg1Axis = MotionEvent.AXIS_GAS;
            }

+            // Make sure the AXIS_Z is sorted between AXIS_RY and AXIS_RZ.
+            // This is because the usual pairing are:
+            // - AXIS_X + AXIS_Y (left stick).
+            // - AXIS_RX, AXIS_RY (sometimes the right stick, sometimes triggers).
+            // - AXIS_Z, AXIS_RZ (sometimes the right stick, sometimes triggers).
+            // This sorts the axes in the above order, which tends to be correct
+            // for Xbox-ish game pads that have the right stick on RX/RY and the
+            // triggers on Z/RZ.
+            //
+            // Gamepads that don't have AXIS_Z/AXIS_RZ but use
+            // AXIS_LTRIGGER/AXIS_RTRIGGER are unaffected by this.
+            //
+            // References:
+            // - https://developer.android.com/develop/ui/views/touch-and-input/game-controllers/controller-input
+            // - https://www.kernel.org/doc/html/latest/input/gamepad.html
+            if (arg0Axis == MotionEvent.AXIS_Z) {
+                arg0Axis = MotionEvent.AXIS_RZ - 1;
+            } else if (arg0Axis > MotionEvent.AXIS_Z && arg0Axis < MotionEvent.AXIS_RZ) {
+                --arg0Axis;
+            }
+            if (arg1Axis == MotionEvent.AXIS_Z) {
+                arg1Axis = MotionEvent.AXIS_RZ - 1;
+            } else if (arg1Axis > MotionEvent.AXIS_Z && arg1Axis < MotionEvent.AXIS_RZ) {
+                --arg1Axis;
+            }
+
            return arg0Axis - arg1Axis;
        }
    }
@@ -210,7 +236,7 @@ class SDLJoystickHandler_API16 extends SDLJoystickHandler {
                    mJoysticks.add(joystick);
                    SDLControllerManager.nativeAddJoystick(joystick.device_id, joystick.name, joystick.desc,
                            getVendorId(joystickDevice), getProductId(joystickDevice), false,
-                            getButtonMask(joystickDevice), joystick.axes.size(), joystick.hats.size()/2, 0);
+                            getButtonMask(joystickDevice), joystick.axes.size(), getAxisMask(joystick.axes), joystick.hats.size()/2, 0);
                }
            }
        }
@@ -291,6 +317,9 @@ class SDLJoystickHandler_API16 extends SDLJoystickHandler {
    public int getVendorId(InputDevice joystickDevice) {
        return 0;
    }
+    public int getAxisMask(List<InputDevice.MotionRange> ranges) {
+        return -1;
+    }
    public int getButtonMask(InputDevice joystickDevice) {
        return -1;
    }
@@ -308,6 +337,43 @@ class SDLJoystickHandler_API19 extends SDLJoystickHandler_API16 {
        return joystickDevice.getVendorId();
    }

+    @Override
+    public int getAxisMask(List<InputDevice.MotionRange> ranges) {
+        // For compatibility, keep computing the axis mask like before,
+        // only really distinguishing 2, 4 and 6 axes.
+        int axis_mask = 0;
+        if (ranges.size() >= 2) {
+            // ((1 << SDL_GAMEPAD_AXIS_LEFTX) | (1 << SDL_GAMEPAD_AXIS_LEFTY))
+            axis_mask |= 0x0003;
+        }
+        if (ranges.size() >= 4) {
+            // ((1 << SDL_GAMEPAD_AXIS_RIGHTX) | (1 << SDL_GAMEPAD_AXIS_RIGHTY))
+            axis_mask |= 0x000c;
+        }
+        if (ranges.size() >= 6) {
+            // ((1 << SDL_GAMEPAD_AXIS_LEFT_TRIGGER) | (1 << SDL_GAMEPAD_AXIS_RIGHT_TRIGGER))
+            axis_mask |= 0x0030;
+        }
+        // Also add an indicator bit for whether the sorting order has changed.
+        // This serves to disable outdated gamecontrollerdb.txt mappings.
+        boolean have_z = false;
+        boolean have_past_z_before_rz = false;
+        for (InputDevice.MotionRange range : ranges) {
+            int axis = range.getAxis();
+            if (axis == MotionEvent.AXIS_Z) {
+                have_z = true;
+            } else if (axis > MotionEvent.AXIS_Z && axis < MotionEvent.AXIS_RZ) {
+                have_past_z_before_rz = true;
+            }
+        }
+        if (have_z && have_past_z_before_rz) {
+            // If both these exist, the compare() function changed sorting order.
+            // Set a bit to indicate this fact.
+            axis_mask |= 0x8000;
+        }
+        return axis_mask;
+    }
+
    @Override
    public int getButtonMask(InputDevice joystickDevice) {
        int button_mask = 0;
@@ -480,13 +546,15 @@ class SDLHapticHandler {
            if (haptic == null) {
                InputDevice device = InputDevice.getDevice(deviceIds[i]);
                Vibrator vib = device.getVibrator();
-                if (vib.hasVibrator()) {
-                    haptic = new SDLHaptic();
-                    haptic.device_id = deviceIds[i];
-                    haptic.name = device.getName();
-                    haptic.vib = vib;
-                    mHaptics.add(haptic);
-                    SDLControllerManager.nativeAddHaptic(haptic.device_id, haptic.name);
+                if (vib != null) {
+                    if (vib.hasVibrator()) {
+                        haptic = new SDLHaptic();
+                        haptic.device_id = deviceIds[i];
+                        haptic.name = device.getName();
+                        haptic.vib = vib;
+                        mHaptics.add(haptic);
+                        SDLControllerManager.nativeAddHaptic(haptic.device_id, haptic.name);
+                    }
                }
            }
        }
@@ -743,7 +811,7 @@ class SDLGenericMotionListener_API26 extends SDLGenericMotionListener_API24 {

    @Override
    public boolean supportsRelativeMouse() {
-        return (!SDLActivity.isDeXMode() || (Build.VERSION.SDK_INT >= 27));
+        return (!SDLActivity.isDeXMode() || Build.VERSION.SDK_INT >= 27 /* Android 8.1 (O_MR1) */);
    }

    @Override
@@ -753,7 +821,7 @@ class SDLGenericMotionListener_API26 extends SDLGenericMotionListener_API24 {

    @Override
    public boolean setRelativeMouseEnabled(boolean enabled) {
-        if (!SDLActivity.isDeXMode() || (Build.VERSION.SDK_INT >= 27)) {
+        if (!SDLActivity.isDeXMode() || Build.VERSION.SDK_INT >= 27 /* Android 8.1 (O_MR1) */) {
            if (enabled) {
                SDLActivity.getContentView().requestPointerCapture();
            } else {
@@ -116,7 +116,7 @@ public class SDLSurface extends SurfaceView implements SurfaceHolder.Callback,
        int nDeviceHeight = height;
        try
        {
-            if (Build.VERSION.SDK_INT >= 17) {
+            if (Build.VERSION.SDK_INT >= 17 /* Android 4.2 (JELLY_BEAN_MR1) */) {
                DisplayMetrics realMetrics = new DisplayMetrics();
                mDisplay.getRealMetrics( realMetrics );
                nDeviceWidth = realMetrics.widthPixels;
@@ -163,7 +163,7 @@ public class SDLSurface extends SurfaceView implements SurfaceHolder.Callback,

        // Don't skip in MultiWindow.
        if (skip) {
-            if (Build.VERSION.SDK_INT >= 24) {
+            if (Build.VERSION.SDK_INT >= 24 /* Android 7.0 (N) */) {
                if (SDLActivity.mSingleton.isInMultiWindowMode()) {
                    Log.v("SDL", "Don't skip in Multi-Window");
                    skip = false;
@@ -30,22 +30,10 @@ compile.exe -q -p -l -O2 -d -s -n -I<sfall_headers_id> <script_name.ssl>

 - Install [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=BGforge.bgforge-mls)

-
-
 ## Run test script

-1. Move compiled `.int` file into game folder as `data/scripts/gl_<script_name>.int`
+1. Move compiled `.int` file into game folder as `scripts/gl_<script_name>.int`

-2. Change `ddraw.ini` and add this section:
-```ini
-[Scripts]
-GlobalScriptPaths=data/scripts/gl*.int
-```
-
-(or add new path using comma as separator)
-
-Note that on non-Windows it have to be `/` as folder separator
-
-3. Run game, check that game displays message about tests
+2. Run game, check that game displays message about tests


@@ -0,0 +1,56 @@
+#include "sfall.h"
+#include "dik.h"
+#include "define_lite.h"
+#include "define_extra.h"
+#include "test_utils.h"
+
+variable refresh_pc_art_test_done := false;
+
+procedure run_refresh_pc_art_test begin
+    variable old_gender := get_critter_stat(dude_obj, STAT_gender);
+    variable new_gender := 1 - old_gender;
+    variable dude_pid := obj_pid(dude_obj);
+    variable old_proto_fid := get_proto_data(dude_pid, PROTO_FID);
+
+    set_pc_base_stat(STAT_gender, new_gender);
+    call assertEquals("gender changes immediately", get_critter_stat(dude_obj, STAT_gender), new_gender);
+    call assertEquals("proto fid unchanged before refresh", get_proto_data(dude_pid, PROTO_FID), old_proto_fid);
+
+    refresh_pc_art;
+
+    variable refreshed_proto_fid := get_proto_data(dude_pid, PROTO_FID);
+    call assertNotEquals("refresh_pc_art updates dude proto fid", refreshed_proto_fid, old_proto_fid);
+
+    if (not critter_inven_obj(dude_obj, INVEN_TYPE_WORN)) then begin
+        call assertEquals("refresh_pc_art updates unarmored dude art", obj_art_fid(dude_obj) bwand 0xFFF, refreshed_proto_fid bwand 0xFFF);
+    end
+
+    set_pc_base_stat(STAT_gender, old_gender);
+    refresh_pc_art;
+    call assertEquals("refresh_pc_art restores original proto fid", get_proto_data(dude_pid, PROTO_FID), old_proto_fid);
+
+    refresh_pc_art_test_done := true;
+    call report_test_results("hook_refresh_pc_art");
+end
+
+procedure keypress_handler begin
+    variable pressed := get_sfall_arg_at(0);
+    variable key := get_sfall_arg_at(1);
+
+    if (not pressed) then return;
+    if (key != DIK_X) then return;
+
+    if (refresh_pc_art_test_done) then begin
+        display_msg("refresh_pc_art test already ran");
+        return;
+    end
+
+    call run_refresh_pc_art_test;
+end
+
+procedure start begin
+    if (not game_loaded) then return;
+
+    display_msg("refresh_pc_art test ready: press X");
+    register_hook_proc(HOOK_KEYPRESS, keypress_handler);
+end
@@ -0,0 +1,26 @@
+#include "test_utils.h"
+#include "sfall.h"
+
+// to test, copy test_extra_msg_file.msg into <game folder>/text/English/game/
+
+procedure start begin
+    variable auto_id;
+    variable duplicate_auto_id;
+
+    display_msg("Testing add_extra_msg_file...");
+
+    call assertEquals("metarule exists", metarule_exist("add_extra_msg_file"), 1);
+
+    auto_id := add_extra_msg_file("test_extra_msg_file.msg");
+    call assertNotEquals("auto id is not load error", auto_id, -2);
+    call assertTrue("auto id lower bound", auto_id >= 0x3000);
+    call assertTrue("auto id upper bound", auto_id <= 0x3FFF);
+    call assertEquals("auto message", message_str_game(auto_id, 100), "auto extra msg");
+
+    duplicate_auto_id := add_extra_msg_file("TEST_EXTRA_MSG_FILE.MSG");
+    call assertEquals("duplicate file returns existing id", duplicate_auto_id, auto_id);
+
+    call assertEquals("missing file", add_extra_msg_file("missing_extra_msg_file.msg"), -2);
+
+    call report_test_results("add_extra_msg_file");
+end
@@ -1,6 +1,6 @@
 #include "lib.arrays.h"
 #include "test_utils.h"
-// #include "define_lite.h"
+#include "define_lite.h"



@@ -9,6 +9,7 @@

 procedure array_test_suite begin
   variable arr, i, arr2, map, k, v, s;
+   variable critter, critter_count;
   test_suite_errors := 0;

   display_msg("Testing arrays_equal functions...");
@@ -164,6 +165,24 @@ procedure array_test_suite begin
   call assertEquals("saved arrays 3", len_array(list_saved_arrays), len_array(arr2) - 1);
   */

+   display_msg("Testing nested expressions...");
+   arr := [["one", "two"]];
+   call assertEquals("nested 1", arr[0][1], "two");
+   arr := [["one", "two"], {"three": ["four", -1]}];
+   call assertEquals("nested 2", arr[1].three[0], "four");
+
+   display_msg("Testing LIST_CRITTERS validity...");
+   critter_count := 0;
+   foreach critter in list_as_array(LIST_CRITTERS) begin
+      critter_count += 1;
+      if (not critter) then begin
+         call assertTrue("LIST_CRITTERS entry is not null", false);
+      end else begin
+         call assertNotEquals("LIST_CRITTERS entry pid is valid", obj_pid(critter), -1);
+      end
+   end
+   call assertTrue("LIST_CRITTERS returns at least one entry", critter_count > 0);
+
   display_msg("All tests finished with "+test_suite_errors+" errors.");

   call report_test_results("arrays");
@@ -178,4 +197,4 @@ end
 procedure start begin
   display_msg("Starting tests");
   call array_test_suite();
-end
+end
@@ -9,9 +9,10 @@ procedure ini_test_suite begin

    // Test Case 1: Valid file, valid section
    result_array := get_ini_section("test.ini", "ValidSection");
-    expected_array := {"Key1": "Value1", "Key2": "2"};
-    call assertEquals("TC1 Size", len_array(result_array), 2);
-    call assertEquals("TC1 Content", arrays_equal(result_array, expected_array), true);
+    call assertEquals("TC1 Size", len_array(result_array), 3);
+    call assertEquals("TC1 Key1", result_array["Key1"], "Value1");
+    call assertEquals("TC1 Key2", result_array["Key2"], "2");
+    call assertEquals("TC1 EmptyValue", result_array["EmptyValue"], "");
    count := 0;
    foreach key_val_pair in result_array begin
        count += 1;
@@ -25,19 +26,22 @@ procedure ini_test_suite begin
    call assertEquals("TC2 get_ini_string string", get_ini_string("test.ini|ValidSection|Key1"), "Value1");
    call assertEquals("TC2 get_ini_setting int", get_ini_setting("test.ini|ValidSection|Key2"), 2);
    call assertEquals("TC2 get_ini_string int", get_ini_string("test.ini|ValidSection|Key2"), "2");
+    call assertEquals("TC2 get_ini_setting empty int", get_ini_setting("test.ini|ValidSection|EmptyValue"), 0);
+    call assertEquals("TC2 get_ini_string empty string", get_ini_string("test.ini|ValidSection|EmptyValue"), "");

    // INI file not found
    result_array := get_ini_section("nonexistent.ini", "AnySection");
    call assertEquals("TC3 Size", len_array(result_array), 0);
    call assertEquals("TC3 Is Map", array_key(result_array, -1), 1); // Should still be an associative array
-    call assertEquals("TC3 get_ini_setting", get_ini_setting("notexist.ini|ValidSection|Key2"), 0);
+    call assertEquals("TC3 get_ini_setting missing file", get_ini_setting("notexist.ini|ValidSection|Key2"), -1);
+    call assertEquals("TC3 get_ini_setting missing key", get_ini_setting("test.ini|ValidSection|MissingKey"), -1);
    call assertEquals("TC3 get_ini_string", get_ini_string("notexist.ini|ValidSection|Key2"), "");

    // Valid file, section not found
    result_array := get_ini_section("test.ini", "NonExistentSection");
    call assertEquals("TC4 Size", len_array(result_array), 0);
    call assertEquals("TC4 Is Map", array_key(result_array, -1), 1);
-    call assertEquals("TC4 get_ini_setting", get_ini_setting("test.ini|NonExistentSection|Key2"), 0);
+    call assertEquals("TC4 get_ini_setting", get_ini_setting("test.ini|NonExistentSection|Key2"), -1);
    call assertEquals("TC4 get_ini_string", get_ini_string("test.ini|NonExistentSection|Key2"), "");


@@ -45,7 +49,7 @@ procedure ini_test_suite begin
    result_array := get_ini_section("test.ini", "EmptySection");
    call assertEquals("TC5 Size", len_array(result_array), 0);
    call assertEquals("TC5 Is Map", array_key(result_array, -1), 1);
-    call assertEquals("TC5 get_ini_setting", get_ini_setting("test.ini|EmptySection|Key2"), 0);
+    call assertEquals("TC5 get_ini_setting", get_ini_setting("test.ini|EmptySection|Key2"), -1);
    call assertEquals("TC5 get_ini_string", get_ini_string("test.ini|EmptySection|Key2"), "");

    // set ini setting
@@ -0,0 +1,38 @@
+#include "define_lite.h"
+#include "sfall.h"
+#include "test_utils.h"
+
+#define TEST_ITEM_PID 40
+
+procedure start begin
+    variable item_a;
+    variable item_b;
+    variable item_c;
+    variable pid_total;
+
+    display_msg("Testing inventory functions...");
+
+    item_a := create_object_sid(TEST_ITEM_PID, 0, 0, -1);
+    item_b := create_object_sid(TEST_ITEM_PID, 0, 0, -1);
+    item_c := create_object_sid(TEST_ITEM_PID, 0, 0, -1);
+
+    add_obj_to_inven(dude_obj, item_a);
+    call assertEquals("single carried object count", obj_is_carrying_obj(dude_obj, item_a), 1);
+    add_obj_to_inven(dude_obj, item_b);
+
+    call assertEquals("merged stack no longer matches original object pointer", obj_is_carrying_obj(dude_obj, item_a), 0);
+    call assertEquals("merged stack matches replacement object pointer", obj_is_carrying_obj(dude_obj, item_b), 2);
+
+    pid_total := obj_is_carrying_obj_pid(dude_obj, TEST_ITEM_PID);
+    call assertTrue("pid total covers both stacks", pid_total >= 2);
+    call assertEquals("pid total matches merged carried stack quantity", pid_total, obj_is_carrying_obj(dude_obj, item_b));
+
+    call assertEquals("object not in inventory returns zero", obj_is_carrying_obj(dude_obj, item_c), 0);
+    call assertEquals("null inventory object returns zero", obj_is_carrying_obj(0, item_a), 0);
+    call assertEquals("null item object returns zero", obj_is_carrying_obj(dude_obj, 0), 0);
+
+    call assertEquals("remove merged stack quantity", rm_mult_objs_from_inven(dude_obj, item_b, 2), 2);
+    destroy_object(item_c);
+
+    call report_test_results("inventory");
+end
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Mike Klaas	f9a5aeff9a	PR feedback	2026-04-10 23:48:45 -07:00
Mike Klaas	bf55a6fbb1	cleanup	2026-04-10 23:48:45 -07:00
github-actions[bot]	9764e2911d	chore: auto-format with clang-format	2026-04-11 06:30:12 +00:00
Mike Klaas	5d5bb78087	Implement perk carryover, plus `get/set_perk_owed` As in Sfall, the 0/1 "perk owned" boolean becomes an unsigned char, allowing perks to accumulate if they are not spent by the time the next perk is granted. Unlike Sfall, we add a mode where perks must be spent "in order". For instance, if the player has not spent their level 3 perk when they hit level 6, they still have 2 perks to spend, but the first perk must be their level 3 perk (with only level 3 perks available), and then they can spend their level 6 perk. This behaviour is configurable to be: vanilla, CE, or Sfall. This value is the same char saved in vanilla and Sfall, so is backward compatible with old saves. To implement `get/set_perk_owed`, perk incrementing has to happen at level-up time instead of the first time the character sheet is opened after level up. This matches Sfall's implementation. It would be pretty easy to implement set_perk_freq / seq_perk_freq / set_perk_level_mod / get_perk_available. For now leaving this out since the PR is big and I'm not sure how often these are used in mods.	2026-04-10 23:21:41 -07:00
Mike Klaas	6f0f68d5aa	Fix crash when using op_pickup with global scripts (#366 ) 1 isn't valid return value here. 0 is success, -1 is failure. Verified against original assembly and dozens of other examples.	2026-04-10 07:53:46 -07:00
Mike Klaas	141c67575f	Update PR template to remove formatting instructions (#365 ) (Auto-format takes care of this)	2026-04-10 07:53:30 -07:00
Mike Klaas	a7a7f0b63c	Implement sfall `signal_close_game` (#364 ) * Implement sfall `signal_close_game` Used by Et tu, but might be useful for LLMs too to quit the game after running a test case. Also added enum for `_user_wants_to_quit`, and did minor reformatting of SFALL_COMPATIBILITY.md	2026-04-10 05:07:43 +00:00
Vlad K github-actions[bot]Mike Klaas	f1d436b144	Move all HRP settings to fallout2.cfg (#345 ) * Moved f2_res.ini settings into regular game config * Rename resolution fields * chore: auto-format with clang-format * Code review fixes * chore: auto-format with clang-format * One-time migration of f2_res.ini to fallout2.cfg (#350) * One-time migration of f2_res.ini to fallout2.cfg --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Mike Klaas <mike.klaas@gmail.com>	2026-04-10 00:40:33 +02:00
Mike Klaas	5939e41da6	Fix crash when global scripts are called reentrantly (#363 ) Saw a crash while testing gl_ShowLootWeight. The issue was that the script uses `repeat(1)`, and we tried to spawn it again while it was running. The fix is to check if the program is already running, using the same logic as the game does when running scripts. This doesn't happen with Sfall since its global script implementation is more integrated with the interpreter. This does point to likely other subtle differences that might matter.	2026-04-09 08:14:03 -07:00
Mike Klaas	7079da6e90	Sfall-style Context for metarules (#354 )	2026-04-08 21:15:15 -07:00
Mike Klaas	1680e885f2	Implement obj_is_carrying_obj Sfall opcode (#362 ) Note: does not include the sfall fix to fix stack counts	2026-04-08 20:52:02 -07:00
Mike Klaas	b31737d4f7	Update vendored Android SDL library (#358 ) * Add Android SDL Java sync guard * Harden Android SDL Java sync guard * Sync Android SDL Java bindings * update to sdk24 (2016) to support newer SDL	2026-04-08 11:57:52 -07:00
Mike Klaas	270f974926	Deobfuscation pass for interpreter.cc/h (#360 ) * Deobfuscation pass for interpreter.cc/h Almost entirely mechanical renaming, with very minor semantic changes: * changed a couple globals to `static` which were only in this file * changed a couple bool-like ints to bool * started adding `const` to local vars	2026-04-07 23:08:20 -07:00
Mike Klaas	92cc37560a	Fix `list_as_array(LIST_CRITTERS)` returning objects with pid=-1 (#359 ) * Fix `list_as_array(LIST_CRITTERS)` returning objects with pid=-1 When using gl_highlighting, I saw: ``` 2026-04-01 12:42:52.824 Fallout II Community Edition[34437:20111056] INFO: Current script: scripts\gl_highlighting.int, procedure ToggleHighlight 2026-04-01 12:42:52.950 Fallout II Community Edition[34437:20111056] INFO: Script Error: scripts\gl_highlighting.int: op_critter_state: obj is NULL 2026-04-01 12:42:52.950 Fallout II Community Edition[34437:20111056] INFO: Error during execution: get_proto_data: bad proto -1 ``` We missed checking that pidType < -1, so we indexed kObjectTypeToListType[-1] which is UB. Either we were lucky and this OOB memory matched, or the compiler was getting cheeky. This fixes the bug and stops the error. * PR feedback	2026-04-06 22:24:49 -07:00
Mike Klaas	3abdbcb53b	Fix Text Delay not saving in options (#357 ) The original clamps to [1, 6], so this was just wrong. Fixes #224	2026-04-05 08:59:30 -07:00
Mike Klaas	b7cacdc6da	Implement HOOK_COMBATTURN (#352 )	2026-04-03 23:25:33 -07:00
Mike Klaas	a98d9d6c26	Implement HOOK_INVENTORYMOVE (#351 )	2026-04-03 22:08:25 -07:00
Mike Klaas	0a64cf4f6b	Partially deobfuscate worldmap.cc (#349 ) I did this as part of looking into `WorldMapSlots=21` support. I don't fully understand that one yet, but this semantics preserving cleanup is worth committing	2026-04-04 04:23:14 +00:00
Mike Klaas	b97c9864aa	Fix global script loading on non-Windows (#347 ) * Fix global script loading on non-Windows Previously, global scripts in .dats and in local FS didn't work due to path separator confusion. Now: * Hardcode global script path to "scripts\gl.int" (windows separator) Use Windows fpattern matching inside of dFile (.dats, which always use windows separators) * Use \-paths when listing found global scripts The awkward part is having to vendor a copy of fpattern to force it to use "windows mode". It's possible that we could use this everywhere since windows allows / as separator, but that could cause bugs where we're using fpattern on the native FS. For now keeping the dFile implementation separate makes sense.	2026-04-01 20:20:57 -07:00
Vlad Kandgithub-actions[bot]	8d0009aa45	Nested array expressions (#346 ) * Nested array expressions * chore: auto-format with clang-format * Code review fixes --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	2026-03-31 20:18:38 +00:00
Vlad K	511d53a615	fix set_proto_data leftover value on stack in case of invalid args + use programPrintError (#344 )	2026-03-31 17:03:50 +02:00
Mike Klaas	f17dd19116	Fix parameter order in metarules set_flags and set_outline. (#341 ) * Fix parameter order in metarules set_flags and set_outline. Also fix missing return val in message_box error path	2026-03-30 08:35:35 -07:00
Mike Klaas	c28c62727f	Implement sfall animation opcodes and metarule (#326 )	2026-03-30 08:24:57 -07:00
Mike Klaas	b14f518714	Comment out hires_stencil debug logs (#339 ) These are a bit too much when debugging other features. Could make this controlled by a bool too if people prefer	2026-03-30 07:53:57 -07:00
Vlad K	6a0bed4433	Death Anim script hook + fall anim fix + related refactoring (#336 ) * actions: refactor code around death anim selection * add Death Anim hook from sfall * AI review fixes * Rename constants for force field PID/FID	2026-03-30 00:23:53 +02:00
Mike Klaas	ce27eb55a1	Sfall compatibility tracker (#334 ) The idea is that modders / contributors could track what is implemented, what is planned/unplanned, &c. There's a risk that we won't keep it up to date, but I think it's a document that we'll need eventually.	2026-03-29 13:32:45 -07:00
Mike Klaas	c240657d0d	Fix two metarule argument popping order errors (#335 ) * Fix two metarule argument popping order errors Also, backfill all errorReturn and argument type validation for metarules	2026-03-29 13:26:34 -07:00
Vlad Kandgithub-actions[bot]	0a73abe67d	Barter hook refactoring and Keypress hook repeat fix (#333 ) * Barter hook refactor: weight compute in separate fn, names and comments for related vars, consistent value args * Hook scripts: use initializer_list for defining args * Keypress Hook: don't trigger on repeat, to match sfall * chore: auto-format with clang-format * Attempt to fix formatting after clang-format * Don't use references for return values, for better readability * chore: auto-format with clang-format * Code review fixes --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	2026-03-29 13:57:30 +02:00
Vlad K	54228248ef	Add barter hook from sfall (#331 ) * Add barter hook from sfall * Code review fixes	2026-03-28 10:43:47 +01:00
Mike Klaas	4eba423399	Use `GameMode::getCurrentGameMode()` instead of custom game mode detection (#328 ) * Use `GameMode::getCurrentGameMode()` instead of custom game mode detection	2026-03-28 00:41:33 -07:00
Mike Klaas	de98136699	Implement sfall tile/path opcodes (#330 ) * Implementation of tile and path opcodes	2026-03-27 22:58:29 -07:00
Mike Klaas	b27b0f03fc	Fix `get_ini_setting` (#329 ) Previously it was returning `0` if the key is missing from the ini file, but the spec is to return -1: https://sfall-team.github.io/sfall/ini-settings/#get_ini_setting Note that if the key _exists_, but is the value is empty (`key=`), sfall returns `0`.	2026-03-26 07:51:00 -07:00
Mike Klaas	9d6f86424e	Implement sfall `add_extra_message_file` (#327 ) https://sfall-team.github.io/sfall/sfall-funcx-macros/#add_extra_msg_file For now we're choosing to not support the 2-arg form. We could return `-1` if the script tries to do this, but if so and it doesn't check for an error, that's likely worse than just crashing at this point. It's essentially an unimplemented opcode.	2026-03-25 21:19:35 -07:00
Mike Klaas	bb65d8d32a	sfall opcode `refresh_pc_art` (#324 ) Needed for RPU	2026-03-24 05:30:08 +00:00
Mike Klaas	c9139f762d	Deobfuscate `scripts.cc/h` (#323 ) * Deobfuscate `scripts.cc/h` Mostly renaming, but also includes: * Some straightforward uninling * Function extraction of a pretty large chunk (elevators) * Simplification of the script loading loop Tested manually	2026-03-22 04:25:46 +00:00
Mike Klaas	beb3c537a4	Fix several compile warnings (#316 ) * Fix several compile warnings Main change is making display functions accept const char* instead of mutating their arguments.	2026-03-21 21:42:15 +00:00
NovaRain	b71f1e7d18	Merge pull request #313 from NovaRain/wmenc_table_fix Fix crash/glitched map when the encounter table has no available entries	2026-03-21 18:33:15 +08:00
Vlad K	b7f2b32b92	Debug window size setting, start debug output earlier and log number of loaded mods (#321 ) * Debug window size setting, start debug output earlier and log total number of mods loaded * Code review fixes	2026-03-21 10:54:32 +01:00
Vlad K	75776e4b5b	HOOK_COMBATDAMAGE (#322 ) * HOOK_COMBATDAMAGE * Fix compilation on 64bit systems * Fix incorrect hit location var	2026-03-20 10:53:03 -07:00
Mike Klaas	5304823f8f	Fix argument order in mapper: mapSetEnteringLocation (#315 ) Mapper's call of this function uses the wrong order compared to all other uses Fixes #294	2026-03-20 13:08:09 +01:00
NovaRain	23e9eab72d	Fix crash/glitched map when the encounter table has no available entries (#311 )	2026-03-19 09:13:43 +08:00