Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
ec19cc6
feat(anchor): add bounded recent-sample consensus for safe re-learning
quasistatic-setup Oct 27, 2026
ac6152a
fix(anchor): re-learn stable warp after hidden transition and clear s…
quasistatic-setup Oct 27, 2026
38e6d30
test(anchor): verify plateau, noise, re-target and reset cases
quasistatic-setup Oct 27, 2026
462d738
test(anchor): preserve assertions under Release NDEBUG
quasistatic-setup Oct 27, 2026
415586b
test/docs(anchor): run regression in CI and document guarded recovery
quasistatic-setup Oct 27, 2026
60b44d6
test/docs(anchor): run regression in CI and document guarded recovery
quasistatic-setup Oct 27, 2026
404414e
test/docs(anchor): run regression in CI and document guarded recovery
quasistatic-setup Oct 27, 2026
02807de
test/docs(anchor): run regression in CI and document guarded recovery
quasistatic-setup Oct 27, 2026
9242e65
fix(anchor): reject recently injected OWN positions from warp consensus
quasistatic-setup Oct 27, 2026
5057581
fix(anchor): quarantine OWN outputs while learning and ignore tainted…
quasistatic-setup Oct 27, 2026
00a8f22
test(anchor): regress synthetic 20px plateau and quiet real-warp reco…
quasistatic-setup Oct 27, 2026
a201ef5
docs(anchor): explain synthetic-output exclusion and verified quiet-t…
quasistatic-setup Oct 27, 2026
46086dc
ci: upgrade checkout and artifact upload to Node.js 24 actions
quasistatic-setup Oct 27, 2026
e58aca5
feat(safety): require repeated unexplained recenter events before all…
quasistatic-setup Oct 27, 2026
1e1b120
fix(hook): pass input until sampled game recenter is independently ve…
quasistatic-setup Oct 27, 2026
ffac738
fix(hook): pass input until sampled game recenter is independently ve…
quasistatic-setup Oct 27, 2026
e669078
fix(anchor): fail open in hidden no-warp mode and gate correction on …
quasistatic-setup Oct 27, 2026
30863d6
test(safety): mode B fail-open and repeated real-warp detection regre…
quasistatic-setup Oct 27, 2026
a41afc9
test/docs(safety): validate no-warp fail-open and record merge blocke…
quasistatic-setup Oct 27, 2026
925d6cb
test/docs(safety): validate no-warp fail-open and record merge blocke…
quasistatic-setup Oct 27, 2026
a17f320
docs: note fail-open recenter gate and Probe B regression
quasistatic-setup Oct 27, 2026
94e4015
docs: replace obsolete anchor heuristics with verified-recenter recovery
quasistatic-setup Oct 27, 2026
5e531eb
fix(safety): revoke stale warp gate and discard pending movement on f…
quasistatic-setup Oct 27, 2026
5ed41c8
docs: clarify verified warp detection and fail-open timeout
quasistatic-setup Oct 27, 2026
4b9c1c4
docs: clarify verified warp detection and fail-open timeout
quasistatic-setup Oct 27, 2026
1409364
docs: clarify verified warp detection and fail-open timeout
quasistatic-setup Oct 27, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ jobs:
name: MSVC x64
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v7

- name: Configure
# No -G: CMake picks the newest Visual Studio on the runner image.
Expand All @@ -21,14 +21,17 @@ jobs:
- name: Build
run: cmake --build build --config Release

- name: Run anchor regression tests
run: ctest --test-dir build -C Release --output-on-failure

- name: Stage the release layout
run: cmake --install build --config Release --prefix stage/RemoteMouseFix-win-x64

- name: Include MouseLookProbe in diagnostic artifact
run: Copy-Item build/bin/Release/MouseLookProbe.exe stage/RemoteMouseFix-win-x64/MouseLookProbe.exe

- name: Upload the build output
uses: actions/upload-artifact@v4
uses: actions/upload-artifact@v7
with:
name: RemoteMouseFix-win-x64
path: stage/RemoteMouseFix-win-x64
Expand Down
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,20 @@ correction is still experimental.

## [Unreleased]

### Fixed

- Require repeated, observed game recenter events before intercepting hidden-cursor
mouse input. Hidden/no-warp mode now passes through (MouseLookProbe B).
Recheck each hold and correction-mode change, keep the 16ms timer unchanged.
Regression cases cover no-warp, false-stable cursor and true warp evidence.

- Relearn a relocated game warp anchor only after repeated unexplained
recenter events; do not trust the former onset-jump/stable-sample shortcut.
On significant relocation, discard queued smoothing movement from the
old coordinate system. Revoke the warp gate after 300 ms of sustained
off-anchor readings to avoid indefinite suppression.
- Add no-warp and recenter-evidence regressions (run in CI).

### Added

- A/B profile enables the optional 250 ms `## TIMING` summary for incoming deltas,
Expand Down
11 changes: 11 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ if(CMAKE_SIZEOF_VOID_P AND NOT CMAKE_SIZEOF_VOID_P EQUAL 8)
message(FATAL_ERROR "RemoteMouseFix currently supports x64 only (got ${CMAKE_SIZEOF_VOID_P}-byte pointers).")
endif()

include(CTest)
option(RMF_BUILD_PROBE "Build MouseLookProbe, the stand-in game used to test the correction" ON)

configure_file(cmake/Version.h.in "${CMAKE_BINARY_DIR}/generated/rmf/Version.h" @ONLY)
Expand Down Expand Up @@ -103,6 +104,16 @@ if(RMF_BUILD_PROBE)
target_link_libraries(MouseLookProbe PRIVATE user32 gdi32 shell32)
endif()

if(BUILD_TESTING)
add_executable(RecentWarpAnchorTests tests/RecentWarpAnchorTests.cpp)
rmf_apply_common_settings(RecentWarpAnchorTests)
add_test(NAME RecentWarpAnchorTests COMMAND RecentWarpAnchorTests)

add_executable(WarpEvidenceTests tests/WarpEvidenceTests.cpp)
rmf_apply_common_settings(WarpEvidenceTests)
add_test(NAME WarpEvidenceTests COMMAND WarpEvidenceTests)
endif()

# What an unpacked release looks like: the two launchers, the programs, README and
# LICENSE at the top, everything else in a folder of its own.
install(TARGETS RemoteMouseFix InputEchoCheck RUNTIME DESTINATION .)
Expand Down
66 changes: 63 additions & 3 deletions docs/diagnostics.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,11 @@ events, which is why it is polled:
- `cursor=HIDDEN` / `SHOWN` bracket the phase in which the game holds the mouse. The
game's cursor warp itself uses `SetCursorPos` and is **invisible** in the event stream;
it shows up only as `cursor_at` here.
- `anchor-learned` is written when a hidden phase ends and one cursor position clearly
dominated its samples (at least 5 hits and 20%). The anchor is stored as a client offset,
so it follows the window when it moves.
- `warp-evidence confirmed` requires repeated unexplained away-then-back
cursor motion correlated with distinct remote input events. Only then is
`anchor-learned` written and mouse-move suppression armed for that hidden
phase. The anchor is stored as a client offset, so it follows the window.
Without evidence, remote events pass through unchanged.
- `clip=CONFINED` means `ClipCursor` is active. WoW 3.3.5a does not use it.
- `focus-left-target` names the new foreground process. No input from it is recorded.

Expand Down Expand Up @@ -302,3 +304,61 @@ to 50 files of 8 MiB in `logs-ab/` and still deletes the oldest matching files.
Before repeating tests, copy important captures into a separate folder that does not
contain the `remotemousefix-*.log` rotation target. Preserve the raw timestamps, and
do not commit session logs to Git.

## Warp-evidence gate: hidden cursor without recenter (mode B)

**Safety requirement:** A hidden cursor alone is not sufficient to intercept
remote mouse input. The prior heuristic would suppress every injected move in
MouseLookProbe mode B and then fail the anchor gate: measured 1,661 suppressed
moves, five applied corrections, 1,476 off-anchor timer skips and a maximum
5.48 s pending age. The 16 ms high-resolution timer was not at fault.

Now the hook passes injected moves through untouched **until** the state
sampler observes multiple unexplained returns to the same interior cursor
point, while a series of distinct remote inputs aims elsewhere. Evidence
must include at least two observed away-then-back transitions, five distinct
remote events, remote travel of at least 60 px and an 80 ms observation span.
Window/desktop edges and locations recently affected by our own SendInput are
excluded. Mere stillness or a jump when the cursor first hides never qualifies.
After a confirmed recenter event, correction may begin for that hold only.
Evidence and permission are reset on hold end, target focus loss or mode change.

A successful classification logs `## STATE warp-evidence confirmed`.
Without this line, no mouse move should be tagged `DROP` in mode B.
For mode C, expect the line followed by `anchor-learned`, actual
`APPLY` and `OWN` movements, and continued 16 ms smoothing.
This is a conservative heuristic, **not** a direct Win32 notification that a
game called SetCursorPos; if samples cannot establish a warp, the fix
intentionally leaves the input alone. Do not weaken this behavior to make
a missed recenter look like a successful correction.

Run all Probe modes over TeamViewer with Fix OFF and ON. Confirm mode B has
no suppressed moves and normal free cursor movement and that mode C still
acquires a warp and rotates smoothly. Finish with a WoW Start-Playing.cmd smoke
test and verify emergency OFF. These runtime tests are required before merging.

## Verified-anchor recovery

If a game changes its recenter position while a hidden-cursor hold is active,
the sampler must **observe new unexplained return events** at the new point.
The same multi-event proof used for initial classification applies again;
an initially hidden cursor, position jump or a stable coordinate alone cannot
authorize an anchor. Candidate positions that coincide with our recent
`SendInput` output are ignored, along with a 160 ms quiet period after output.

A validated relocation logs `## STATE warp-evidence confirmed` and
`anchor-learned`. If the new client-relative anchor differs from the old
one by more than the configured tolerance, the main message loop discards
smoothing movement queued against the previous anchor and logs
`## SMOOTH RESET reason=anchor-relearned`. The sampler never sends input.

An anchor classified in one hold is **never reused as proof** in the next
hold. Until genuine recenter behavior is observed again, events pass through.
A temporary loss of correction is safer than suppressing cursor movements
in a game with no warp. If the sampled cursor remains outside an already
verified anchor for more than 300 ms (excluding recent own output), the
classification is revoked, pending movement is discarded, and input passes
through again (`## STATE warp-evidence revoked`). Runtime verification must include moving the WoW
window before the next hold, all Probe A/B/C modes, loss of target focus,
the OFF/relative modes and emergency-off.

10 changes: 10 additions & 0 deletions include/rmf/MouseHook.h
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,16 @@ class MouseHook {
// Learned warp anchor, as an offset inside the target client area so it survives
// the window being moved.
std::atomic<bool> anchorValid {false};
// Explicitly armed only after multiple observed, unexplained recenter
// events. Hidden cursor without warp MUST pass through (Probe mode B).
std::atomic<bool> warpVerified {false};

// Single hook writer; odd/even version makes the last external injected
// move an atomic snapshot for the state sampler, without a lock or I/O.
std::atomic<std::uint64_t> remoteVersion {0};
std::atomic<long> remoteX {0};
std::atomic<long> remoteY {0};
std::atomic<std::uint64_t> remoteMs {0};
std::atomic<long> anchorOffsetX {0};
std::atomic<long> anchorOffsetY {0};
};
Expand Down
79 changes: 79 additions & 0 deletions include/rmf/RecentWarpAnchor.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
#pragma once

#include <windows.h>
#include <array>
#include <cstddef>
#include <cstdint>
#include <cstdlib>

namespace rmf {

// Recent sampler readings only. This is NOT proof of a game warp on its own:
// a motionless remote cursor can also produce a stable position.
// Callers must independently establish a cursor-recenter transition.
class RecentWarpAnchor {
public:
void Reset() {
count_ = 0;
next_ = 0;
observedOwnCount_ = 0;
}

// Keep only samples collected during a quiet interval without our SendInput
// output. OWN cursor locations are not independent evidence of a game warp.
// Returns true only when the sample was admitted to the consensus window.
bool Observe(POINT point, std::uint64_t ownCount, POINT lastOwnTarget,
std::uint64_t nowMs, std::uint64_t lastOwnOutputMs) {
const bool outputChanged = ownCount != observedOwnCount_;
observedOwnCount_ = ownCount;
const bool recentlyOutput = lastOwnOutputMs != 0 &&
(nowMs < lastOwnOutputMs || nowMs - lastOwnOutputMs < 160);
const bool atOwnTarget = ownCount != 0 &&
std::labs(point.x - lastOwnTarget.x) <= 2 &&
std::labs(point.y - lastOwnTarget.y) <= 2;
if (outputChanged || recentlyOutput || atOwnTarget) {
ClearSamples();
return false;
}
Add(point);
return true;
}

void Add(POINT point) {
samples_[next_] = point;
next_ = (next_ + 1) % samples_.size();
if (count_ < samples_.size()) ++count_;
}

bool Stable(POINT& result, unsigned& hits, unsigned& total) const {
hits = 0;
total = static_cast<unsigned>(count_);
if (count_ < 8) return false;

for (std::size_t i = 0; i < count_; ++i) {
unsigned matches = 0;
for (std::size_t j = 0; j < count_; ++j) {
if (samples_[i].x == samples_[j].x &&
samples_[i].y == samples_[j].y) ++matches;
}
if (matches > hits) {
hits = matches;
result = samples_[i];
}
}
return hits >= 8 && hits * 100u >= total * 75u;
}

private:
void ClearSamples() {
count_ = 0;
next_ = 0;
}

std::array<POINT, 12> samples_ {};
std::size_t count_ = 0;
std::size_t next_ = 0;
std::uint64_t observedOwnCount_ = 0;
};

} // namespace rmf
148 changes: 148 additions & 0 deletions include/rmf/WarpEvidence.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
#pragma once

#include <windows.h>

#include <array>
#include <cstdint>
#include <cstdlib>

namespace rmf {

// Only a *repeated unexplained return* toward one interior location constitutes
// evidence that a hidden cursor is being recentered by the game. A hidden or
// motionless cursor alone is not evidence (MouseLookProbe mode B).
struct RemotePointerSample {
POINT point {0, 0};
std::uint64_t serial = 0;
std::uint64_t tickMs = 0;
};

class WarpEvidence {
public:
void Reset() {
candidates_ = {};
havePrevious_ = false;
observedOwnCount_ = 0;
}

bool Observe(POINT cursor, RECT client, RECT desktop, RemotePointerSample remote,
std::uint64_t nowMs, std::uint64_t ownCount,
POINT lastOwnTarget, std::uint64_t lastOwnOutputMs,
bool ownOutputInHold, POINT& confirmed, unsigned& returns) {
const bool ownChanged = ownCount != observedOwnCount_;
observedOwnCount_ = ownCount;
const bool recentOwn = ownOutputInHold && lastOwnOutputMs != 0 &&
(nowMs < lastOwnOutputMs || nowMs - lastOwnOutputMs < 160);
const bool ownTarget = ownOutputInHold &&
Close(cursor, lastOwnTarget, 2);
const bool recentlyRemote = remote.serial != 0 &&
remote.tickMs <= nowMs && nowMs - remote.tickMs <= 80;
const bool interior = Inside(cursor, client, 24) &&
Inside(cursor, desktop, 24);

// If our own SendInput might explain this position, the complete
// hypothesis is tainted. Do not resume an old count later.
if (ownChanged || recentOwn || ownTarget) {
ClearCandidates();
}

bool verified = false;
if (!ownChanged && !recentOwn && !ownTarget &&
recentlyRemote && interior && Far(cursor, remote.point, 45)) {
Candidate* slot = nullptr;
for (Candidate& candidate : candidates_) {
if (candidate.active && nowMs >= candidate.lastMs &&
nowMs - candidate.lastMs <= 280 &&
Close(candidate.anchor, cursor, 3)) {
slot = &candidate;
break;
}
}
if (!slot) {
for (Candidate& candidate : candidates_) {
if (!candidate.active || nowMs < candidate.lastMs ||
nowMs - candidate.lastMs > 280) {
slot = &candidate;
break;
}
}
}
if (!slot) {
slot = &candidates_[0];
for (Candidate& candidate : candidates_) {
if (candidate.lastMs < slot->lastMs) slot = &candidate;
}
}
const bool same = slot->active && nowMs >= slot->lastMs &&
nowMs - slot->lastMs <= 280 &&
Close(slot->anchor, cursor, 3);

if (!same) {
*slot = Candidate{};
slot->active = true;
slot->anchor = cursor;
slot->firstMs = nowMs;
slot->firstRemote = remote.point;
}

if (remote.serial != slot->lastSerial) {
slot->lastSerial = remote.serial;
slot->lastMs = nowMs;
++slot->hits;
if (Far(slot->firstRemote, remote.point, 60)) {
slot->remoteMoved = true;
}
// This is the critical distinction from a stationary cursor:
// we must actually SEE the cursor away from this same point,
// then back while the latest remote input aims elsewhere.
if (havePrevious_ && Far(previousCursor_, slot->anchor, 45)) {
++slot->returns;
}
if (!slot->reported && slot->hits >= 5 && slot->returns >= 2 &&
slot->remoteMoved && nowMs - slot->firstMs >= 80) {
slot->reported = true;
confirmed = slot->anchor;
returns = slot->returns;
verified = true;
}
}
}

previousCursor_ = cursor;
havePrevious_ = true;
return verified;
}

private:
struct Candidate {
bool active = false;
bool reported = false;
bool remoteMoved = false;
POINT anchor {0, 0};
POINT firstRemote {0, 0};
std::uint64_t firstMs = 0;
std::uint64_t lastMs = 0;
std::uint64_t lastSerial = 0;
unsigned hits = 0;
unsigned returns = 0;
};

static bool Close(POINT a, POINT b, long delta) {
return std::labs(a.x - b.x) <= delta && std::labs(a.y - b.y) <= delta;
}
static bool Far(POINT a, POINT b, long delta) {
return std::labs(a.x - b.x) >= delta || std::labs(a.y - b.y) >= delta;
}
static bool Inside(POINT p, RECT rect, long margin) {
return p.x >= rect.left + margin && p.x < rect.right - margin &&
p.y >= rect.top + margin && p.y < rect.bottom - margin;
}
void ClearCandidates() { candidates_ = {}; }

std::array<Candidate, 4> candidates_ {};
POINT previousCursor_ {0, 0};
bool havePrevious_ = false;
std::uint64_t observedOwnCount_ = 0;
};

} // namespace rmf
Loading