# cheatrs

**Repository Path**: hXoreyer/cheatrs

## Basic Information

- **Project Name**: cheatrs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cheatrs 0.2.0

`cheatrs` 是一个可复用的 Windows 库：核心包含进程枚举、架构检测、模块
查询、类型化进程内存和轻量数学类型。输入、ImGui+D3D11 覆盖层、实验性
ProbeHook 和 tracing 都必须显式启用 feature。

该项目用于获得授权的调试、自动化和安全研究。调用方负责目标程序许可、
Windows 完整性级别和反作弊/安全策略；库不会绕过权限检查。

## Feature

```toml
[dependencies]
cheatrs = "0.2"

# 按需启用；默认只编译核心
cheatrs = { version = "0.2", features = ["input", "imgui-overlay"] }
```

| feature | 内容 |
| --- | --- |
| `input` | 类型化键盘/鼠标 `SendInput`，含虚拟桌面绝对坐标说明 |
| `imgui-overlay` | 单窗口透明 D3D11 + DirectComposition + ImGui，支持跟随目标 HWND 或固定矩形 |
| `hook` | x86/x64 同位的 `ProbeHook` 解码/状态 API；远程安装仍明确标记 experimental limitation |
| `tracing` | 进程打开、覆盖层生命周期和 Hook 拒绝路径的可选诊断事件 |

## 核心示例

```rust,no_run
use cheatrs::{Address, Process};

fn read_value(pid: u32, address: u64) -> cheatrs::Result<u32> {
    let process = Process::open_read(pid)?;
    process.read(Address::new(address))
}
```

只读句柄使用 `open_read`；需要写入时显式使用 `open_read_write`。所有安全
类型化读写要求 `bytemuck::Pod`，字节 API 提供 `read_exact`/`read_partial` 和
`write_all`/`write_partial`。任意布局的逃生口是 `unsafe`，并带有 `# Safety`
契约。

`Error` 是结构化枚举，可匹配 `Process`、`Module`、`Memory`、`Architecture`、
`Permission`、`Input`、`Overlay` 和 `Hook`，并通过 `win32_code()` 保留底层
Win32/HRESULT 原始错误码。

在 x64 构建中，`Process` 可按权限打开并读写 x86 目标；x86 构建不会操作 x64
目标。`hook` 仍要求与目标严格同位，且当前版本的远程安装始终拒绝执行。

## 线程和覆盖层

`Process` 可通过共享引用跨线程使用。ImGui Overlay 保存创建线程标记并在类型
中包含非 `Send`/`Sync` 标记；调用方在创建线程驱动 `poll_events`，然后让
`begin_frame` 返回的 `OverlayFrame` 借用 UI 并消费 `frame.render()`，或使用
`run`。默认目标模式跟随目标 HWND，也可用 `OverlayConfig::fixed_rect`。
最小化、目标退出、DPI、尺寸和设备/交换链恢复都会通过生命周期事件返回。
点击穿透可由 `Overlay::set_click_through` 或当前 `OverlayFrame` 安全切换；
调用方可根据本帧 `want_capture_mouse` 自己选择策略，库不会在收到穿透鼠标
后假装仍能可靠捕获全部事件。

覆盖层使用 D3D11 + DirectComposition 合成透明窗口，交换链采用预乘 Alpha；
背景始终为透明，`OverlayConfig::alpha` 只控制 ImGui 内容的整体透明度（0 为
全透明，255 为不透明）。创建覆盖层时，创建线程会临时切换到
PerMonitorV2 DPI awareness，并在覆盖层销毁时恢复原上下文；覆盖层及其窗口、
D3D11 immediate context 和 ImGui context 必须在创建线程上使用和销毁。

ImGui 0.8 后端上传内置字体纹理；自定义 `TextureId`、`RawCallback` 和
`ResetRenderState` 绘制命令会返回结构化 `OverlayErrorKind::Unsupported`，
不会静默丢弃绘制。

运行透明覆盖层示例（Windows）：

```text
cargo run --example overlay --features imgui-overlay
```

示例使用 `poll_events`、`begin_frame` 和 `OverlayFrame::render` 手动驱动，
没有调用 `Overlay::run`：屏幕坐标约 `(100, 100)` 的 `800x600` 覆盖层中，
`[40, 40]` 附近是 `360x240` 的控件窗口，包含按钮计数、checkbox 和可拖动
slider。ImGui UI 区域会捕获鼠标，其他透明像素会点击穿透到底层窗口；后端在
每帧用 `GetCursorPos` + `ScreenToClient` 更新 ImGui 光标位置，所以从穿透区
进入 UI 时会在一帧内解除穿透，拖动控件时也会保持捕获。背景 draw list 在
`[600, 300]` 附近绘制红色实心圆；它只是绘制几何体，不是交互区域。按
`Ctrl+C` 退出。

## 验证

```text
cargo fmt --check
cargo check --no-default-features
cargo check --no-default-features --features input
cargo check --no-default-features --features hook
cargo check --no-default-features --features imgui-overlay
cargo test --all-targets
cargo test --all-features --all-targets
cargo clippy --all-features --all-targets -- -D warnings
```

MSRV 为 Rust 1.78（Cargo.lock 使用 v4 格式）。

`hook` feature 的远程注入部分不会接受任意机器码；若目标 ABI/安全探针未通过
审计，`install` 会返回 `HookErrorKind::ExperimentalLimitation`，而不会伪装
成已安装状态。迁移旧版 API 请参阅 [MIGRATION.md](MIGRATION.md)。