UniformAimming(鼠标灵敏度)

更新

v0.03 修复了高倍镜的灵敏度过慢问题
v0.03 Fixed the issue of high magnification scope sensitivity being too slow

# STALKER 2 FOV-灵敏度自动绑定器 v0.03

# STALKER 2 FOV-Sensitivity Auto Binder v0.03

## 功能描述

这是一个为《S.T.A.L.K.E.R. 2: Heart of Chornobyl》设计的模组，能够自动根据FOV（视野）变化调整鼠标灵敏度，实现基于屏幕距离的瞄准一致性（就像cod和战地的统一士兵瞄准选项一样）。无论使用瞄准镜、望远镜还是其他光学设备，都能保持一致的瞄准体验。与设置中原有的灵敏度设置兼容，并可以精细调整鼠标灵敏度到更广范围。

This is a mod for "S.T.A.L.K.E.R. 2: Heart of Chornobyl" that automatically adjusts mouse sensitivity based on FOV (Field of View) changes, achieving screen-distance-based aiming consistency. Whether using scopes, binoculars, or other optical devices, it maintains a consistent aiming experience.

## 主要特性

- 🔄 自动FOV检测 - 每100毫秒检测一次FOV变化
- 🎯 智能灵敏度调整 - 基于当前FOV精确计算合适的灵敏度
- 🎮 屏幕距离一致性 - 保持鼠标移动在屏幕上的物理距离一致
- ⚙️ 实时基准调整 - 支持游戏中实时调整基准灵敏度和统一瞄准系数
- 💾 配置保存 - 按数字键0保存用户设置到配置文件
- 🔧 热重载支持 - 支持模组热重载（部分）
- 🐛 调试模式 - 详细的调试信息输出，便于故障排除

- 🔄 Automatic FOV Detection - Detects FOV changes every 100ms
- 🎯 Smart Sensitivity Adjustment - Precisely calculates appropriate sensitivity based on current FOV
- 🎮 Screen Distance Consistency - Maintains consistent physical mouse movement distance on screen
- ⚙️ Real-time Base Adjustment - Supports real-time base sensitivity and compensation factor adjustment in-game
- 💾 Configuration Saving - Press Numpad 0 to save user settings to configuration file
- 🔧 Hot Reload Support - Supports mod hot reloading (partial)
- 🐛 Debug Mode - Detailed debug information output for troubleshooting

## 安装方法

1. 确保已安装UE4SS 2.5.2或更高版本
2. 将 UniformAimming 文件夹复制到 Stalker2/Binaries/Win64/ue4ss/Mods/ 目录
3. 修改 Mods/目录下的mods.txt文件，添加UniformAimming:1字段
4. 启动游戏，模组将自动加载
5. 首次运行时会创建默认配置文件

1. Ensure UE4SS 2.5.2 or later is installed
2. Copy the UniformAimming folder to Stalker2/Binaries/Win64/ue4ss/Mods/
3. Modify the mods.txt file in the Mods/ directory, add UniformAimming:1 field
4. Launch the game, the mod will load automatically
5. Default configuration file will be created on first run

## 使用方法

### 自动功能

- 模组会自动检测FOV变化并调整灵敏度
- 当使用瞄准镜、望远镜等改变FOV时，灵敏度会自动适应
- FOV越小（放大倍率越大），灵敏度越低，保持瞄准一致性
- 配置会自动保存，下次启动游戏时自动加载

- The mod automatically detects FOV changes and adjusts sensitivity
- When using scopes, binoculars, etc. that change FOV, sensitivity automatically adapts
- Smaller FOV (higher magnification) results in lower sensitivity, maintaining aiming consistency
- Configuration is automatically saved and loaded on next game launch

### 手动控制

| 按键 | 功能 |
|-----------|----------------|
| 小键盘 8 | 基准灵敏度 +0.1 |
| 小键盘 2 | 基准灵敏度 -0.1 |
| 小键盘 6 | 基准灵敏度 +0.01 |
| 小键盘 4 | 基准灵敏度 -0.01 |
| 小键盘 9 | 统一瞄准系数 +10 |
| 小键盘 7 | 统一瞄准系数 -10 |
| 小键盘 3 | 统一瞄准系数 +1 |
| 小键盘 1 | 统一瞄准系数 -1 |
| 小键盘 5 | 重置灵敏度和统一系数为默认值 |
| 小键盘 0 | 保存当前配置 |
| F9键 | 切换Debug模式 |
| K键 | 打印可用按键列表（仅在Debug模式下） |
| L键 | 显示当前FOV并设置极低灵敏度（仅在Debug模式下） |

### 使用建议

- 建议在游戏内菜单将鼠标灵敏度和瞄准灵敏度设置为同样的较大数值
- 基准灵敏度1.0对应游戏内默认灵敏度
- 统一瞄准系数控制FOV变化的补偿程度，0为完全补偿，正值减少补偿
- 使用小键盘0键保存当前设置，下次启动游戏时自动加载

- Recommended to set mouse sensitivity and aim sensitivity to the same larger value in-game menu
- Base sensitivity 1.0 corresponds to default in-game sensitivity
- Compensation factor controls the degree of FOV change compensation, 0 for full compensation, positive values reduce compensation
- Use Numpad 0 to save current settings, automatically loaded on next game launch

## 技术细节

### 算法原理

灵敏度计算公式：
<br />CurrentSensitivity = BaseSensitivity × (1 + (CurrentFOV/BaseFOV - 1) × (1 - CompensationFactor/200)) <br />

其中：
- 基准FOV: 90°
- 基准灵敏度: 1.0（默认值）
- 统一瞄准系数: 0-200范围，控制补偿程度，数值越高则开镜时的相对灵敏度越高。设为0时完全补偿为和屏幕距离相关的瞄准体验，设为200时不进行补偿，瞄准只控制角度。

Sensitivity calculation formula based on trigonometry:
<br />CurrentSensitivity = BaseSensitivity × (1 + (CurrentFOV/BaseFOV - 1) × (1 - CompensationFactor/200)) <br />

Where:
- Base FOV: 90°
- Base Sensitivity: 1.0 (default)
- Compensation Factor: 0-200 range, controls compensation degree

### 默认设置

- 基准FOV: 90°
- 基准灵敏度: 1.0
- 统一瞄准系数: 0
- 检测间隔: 100ms

### Debug模式

Debug模式提供了详细的调试信息输出，帮助开发者或高级用户诊断问题：

- F9键 - 切换Debug模式开关
- Debug模式开启时：显示详细的FOV检测、灵敏度计算、对象初始化等信息
- Debug模式关闭时：仅显示错误信息和关键状态变化，减少控制台输出
- K键和L键 - 仅在Debug模式下生效的调试功能

Debug mode provides detailed debug information output to help developers or advanced users diagnose issues:

- F9 Key - Toggle Debug mode on/off
- When Debug mode is on: Shows detailed FOV detection, sensitivity calculation, object initialization, etc.
- When Debug mode is off: Only shows error messages and critical state changes, reducing console output
- K and L Keys - Debug functions that only work in Debug mode

## 版本信息

v0.02 - Nexus Mods发布版本
- ✅ 完整的FOV-灵敏度自动绑定功能
- ✅ 实时基准灵敏度和统一瞄准系数调整
- ✅ 配置自动保存和加载
- ✅ 完整的调试和测试功能
- ✅ 热重载部分支持
- ✅ 游戏重新加载时的自动初始化
- ✅ 完整的README文档和安装说明
- ✅ 支持N网发布

v0.01 - 初始版本
- 基础FOV-灵敏度自动绑定功能
- 实时基准灵敏度调整
- 调试和测试功能

v0.02 - Nexus Mods Release
- ✅ Complete FOV-sensitivity auto-binding functionality
- ✅ Real-time base sensitivity and compensation factor adjustment
- ✅ Automatic configuration saving and loading
- ✅ Complete debug and testing features
- ✅ Hot reload support (partial)
- ✅ Automatic initialization on game reload
- ✅ Complete README documentation and installation instructions
- ✅ Ready for Nexus Mods release

v0.01 - Initial Release
- Basic FOV-sensitivity auto-binding functionality
- Real-time base sensitivity adjustment
- Debug and testing features

## 已知问题

- 热重载时可能出现游戏崩溃（建议回退到主菜单再重载mod）
- 某些过场动画期间FOV获取可能失败
- 灵敏度调整可能有轻微延迟（100ms检测间隔）
- 与其他修改鼠标灵敏度的模组可能冲突

- Game may crash during hot reload (recommend returning to main menu then reload mod)
- FOV acquisition may fail during certain cutscenes
- Slight delay in sensitivity adjustment (100ms detection interval)
- May conflict with other mods that modify mouse sensitivity

## 兼容性

- ✅ UE4SS 2.5.2+
- ✅ STALKER 2 1.7版本
- ❌ 与其他修改鼠标灵敏度的模组可能冲突
- ✅ 支持游戏重新加载和热重载

- ✅ UE4SS 2.5.2+
- ✅ STALKER 2 Version 1.7
- ❌ May conflict with other mods that modify mouse sensitivity
- ✅ Supports game reload and hot reload

## 故障排除

1. 模组不工作：检查UE4SS是否正确安装，确保UniformAimming文件夹在正确位置
2. 灵敏度不变化：按F9启用Debug模式，查看FOV检测和计算信息
3. 配置不保存：确保有写入权限，检查ModSettings.lua文件
4. 按键无响应：确保使用小键盘，检查Num Lock状态

1. Mod not working: Check if UE4SS is properly installed, ensure UniformAimming folder is in correct location
2. Sensitivity not changing: Press F9 to enable Debug mode, check FOV detection and calculation info
3. Configuration not saving: Ensure write permissions, check ModSettings.lua file
4. Keys not responding: Ensure using numpad, check Num Lock status

## 开发计划

### 后续版本计划

- 🎨 创建GUI界面 - 提供图形用户界面，便于用户直观调整设置
- 🔌 脱离对UE4SS的依赖 - 开发独立版本，减少安装复杂度
- 🔄 实时配置预览 - 在GUI中实时预览灵敏度变化效果

- 🎨 Create GUI Interface - Provide graphical user interface for intuitive settings adjustment
- 🔌 Remove UE4SS Dependency - Develop standalone version to reduce installation complexity
- 🔄 Real-time Configuration Preview - Preview sensitivity changes in real-time within GUI

## 开发者信息

这个模组使用Lua脚本开发，基于UE4SS框架。如果你遇到问题或有改进建议，请在N网页面留言。

主要文件：
- main.lua - 主逻辑和FOV检测
- config.lua - 配置管理
- input.lua - 按键绑定
- debug.lua - 调试功能
- ModSettings.lua - 用户配置

This mod is developed using Lua scripts based on the UE4SS framework. If you encounter issues or have suggestions for improvement, please leave a comment on the Nexus Mods page.

Main files:
- main.lua - Main logic and FOV detection
- config.lua - Configuration management
- input.lua - Key bindings
- debug.lua - Debug functionality
- ModSettings.lua - User configuration

---

享受更一致的瞄准体验！