Unstable FPS Controls: Crosshair and Mouse Lock Issues in XtMapper

[SoufianoDev]

I noticed that the current behavior of XtMapper is not fully compatible with the game Free Fire, especially when it comes to the crosshair logic and mouse behavior during aiming.

When entering aiming mode in shooter games, moving the mouse sometimes triggers unexpected in-game events. Instead of only controlling the camera, the mouse movement can accidentally activate other actions such as moving the character, opening the map, activating the scope, or interacting with other on-screen buttons. This makes aiming unstable and frustrating.

In aiming mode the mouse should stay locked to the crosshair position and should not interact with other UI elements. The expected behavior is that the crosshair stays fixed on the screen while mouse movement only rotates the camera. Right now this does not seem to happen consistently.

Another limitation is that aiming mode is currently forced to the right mouse button. It would be much better if users could choose their own activation key or mouse button instead of having it fixed.

I also noticed that some mapped buttons do not always keep their saved coordinates after configuration, which sometimes causes them to shift from their intended position.

One idea that could improve the experience for shooter games like Free Fire would be a more structured aiming system similar to what Android emulators provide. For example, a centered crosshair overlay that stays fixed on the screen, proper mouse locking and blocking when aim mode is active, and customizable activation keys. It would also help if, when a user places a crosshair element in the editor, a fire button element appears as well so the player can position it directly on top of the game's shoot button.

These kinds of improvements could make the tool much more comfortable to use for FPS-style games.

[Xtr126]

Another limitation is that aiming mode is currently forced to the right mouse button. It would be much better if users could choose their own activation key or mouse button instead of having it fixed.

One idea that could improve the experience for shooter games like Free Fire would be a more structured aiming system similar to what Android emulators provide. For example, a centered crosshair overlay that stays fixed on the screen, proper mouse locking and blocking when aim mode is active, and customizable activation keys. It would also help if, when a user places a crosshair element in the editor, a fire button element appears as well so the player can position it directly on top of the game's shoot button.

You can already set your own key for activation from settings. And using middle mouse button is being worked on #185

Aiming always starts from the crosshair and should not interact with UI elements, probably free fire is doing something weird, I will have a look at it later. You also have the option to restrict the area for aiming.

I also noticed that some mapped buttons do not always keep their saved coordinates after configuration, which sometimes causes them to shift from their intended position.

That was also reported in #186 and being fixed.

[SoufianoDev]

Another limitation is that aiming mode is currently forced to the right mouse button. It would be much better if users could choose their own activation key or mouse button instead of having it fixed.
One idea that could improve the experience for shooter games like Free Fire would be a more structured aiming system similar to what Android emulators provide. For example, a centered crosshair overlay that stays fixed on the screen, proper mouse locking and blocking when aim mode is active, and customizable activation keys. It would also help if, when a user places a crosshair element in the editor, a fire button element appears as well so the player can position it directly on top of the game's shoot button.

You can already set your own key for activation from settings. And using middle mouse button is being worked on #185

Aiming always starts from the crosshair and should not interact with UI elements, probably free fire is doing something weird, I will have a look at it later. You also have the option to restrict the area for aiming.

I also noticed that some mapped buttons do not always keep their saved coordinates after configuration, which sometimes causes them to shift from their intended position.

That was also reported in #186 and being fixed.

Note: I am using cage-xtmapper

[Xtr126]

About cage-xtmapper, I don't handle middle mouse button yet, but the rest should work.

[Xtr126]

I can also reproduce the unstable aiming control in cage-xtmapper. I've somewhat fixed it in 5d6e83a.

[SoufianoDev]

I can also reproduce the unstable aiming control in cage-xtmapper. I've somewhat fixed it in 5d6e83a.

I am currently working on this project locally on my machine, and these changes represent the cumulative improvements and fixes I have reached as of this moment.

The primary focus of this development cycle has centered on three critical areas: modernizing the codebase with contemporary language features, fortifying thread-safety guarantees in core event handling, and enhancing platform compatibility across device configurations.

Beginning with the language foundation, I have systematically migrated four essential activities from Java to Kotlin: MainActivity, InfoActivity, ImportExportActivity, and key UI component classes including Camera and Crosshair. This shift enriches the codebase with Kotlin's null-safety guarantees, more concise syntax, and better interoperability with modern Android libraries while maintaining full backward compatibility.

The most substantial technical improvement addresses a critical data race condition in MouseEventHandler. The mouseAimActive field and mouseAimOrCameraHandler instance variable are now declared as volatile, ensuring strict visibility guarantees across thread boundaries. Previously, the native input thread could observe stale values written by the main thread, allowing unconstrained cursor event injection into active game touch zones.

Complementary to this, the triggerMouseAimOrCamera method now employs explicit synchronization within a synchronized block, guaranteeing atomic state transitions and proper handler initialization before mouseAimActive is exposed to concurrent readers. This architectural refinement directly prevents input bleed during aim mode activation — a crash-prone race condition observed in shooter games.

An additional event handling bug has been corrected in the mouse button fall-through case: the BTN_MIDDLE, BTN_SIDE, and BTN_EXTRA press handlers now explicitly break before reaching the REL_WHEEL case. This eliminates spurious scroll events that would inadvertently interact with game UI elements such as scope toggles or map zones during active aim mode.

Defensive null-safety enhancements throughout EditorUiComponentList remove all unsafe double-bang operators and enforce non-nullable parameters for callback and context references. Rather than forcing developers to assert non-null values, the type system now makes these guarantees explicit. Safe Elvis operators replace unsafe casts during component classification, and lambda syntax has been modernized to leverage Kotlin's expressive type inference.

Android API compatibility has been strengthened through explicit version checks. TouchpadDataReceiver now gates the logcat ProcessBuilder invocation behind Build.VERSION.SDK_INT >= Build.VERSION_CODES.O, preventing runtime failures on devices below Android 8.0.

Window type declarations for overlay components in Camera now dynamically select TYPE_APPLICATION_OVERLAY on Oreo+ devices while gracefully degrading to TYPE_SYSTEM_ALERT on earlier versions.

The AndroidManifest.xml has also been augmented with tools:ignore directives for protected permissions (DIAGNOSTIC, VIRTUAL_INPUT_DEVICE, INTERNAL_SYSTEM_WINDOW, INJECT_EVENTS) and foreground service lint warnings, signaling to the build system that these permissions are intentional and justified for the remote input server functionality.

New localization strings have been added to all language variants (English, Arabic, Spanish, French, Punjabi, Portuguese, Russian, and Chinese Simplified) to support refined import/export messaging. This allows users to receive clearer feedback on backup operations and profile migration success or failure across eight language communities.

Performance profiling infrastructure has also been introduced through the addition of baseline profiles in app/release/baselineProfiles/. These tiered profiles (slots 0 and 1) allow the Ahead-of-Time compiler to prioritize method compilation strategies, reducing cold startup latency and improving throughput for frequently invoked code paths during gameplay.

---

Current Testing Observations

At the moment, I have not yet conducted extensive stress testing, but during preliminary manual testing I noticed several behavioral improvements and one important issue:

• While using Crosshair Mode, when transitioning into shooting mode and moving the mouse, there appears to be reduced interaction with UI areas that should not receive input, which suggests the new synchronization and event handling changes are improving input isolation.

• However, I also observed a serious issue:
  Mouse Walk behavior is sometimes triggered even though it has not been configured as a DPad option. This indicates that some input mapping logic may still be leaking into unintended control paths during aim or shooting transitions.

This issue has been documented and will require further investigation before the changes can be considered fully stable.

---

These changes collectively represent measurable progress toward production readiness: eliminating thread-safety defects that could corrupt game state, adopting type-safe language semantics that prevent entire classes of runtime exceptions, and strengthening compatibility across Android devices ranging from API 26 through API 35+.

I would welcome your feedback on these improvements and would be happy to formally submit them as a Pull Request from my local dev branch in 5254349 whenever you are ready to review.