🎮 Osynic Pad

Rust 编写的游戏手柄到键盘映射工具

Crates.io

English | 中文

📋 简介

Osynic Pad 是一个功能强大的游戏手柄到键盘映射工具库，使用 Rust 编写。它支持 Xbox、PlayStation 等多种主流游戏手柄，通过交互式菜单和灵活的配置系统，让你轻松将手柄按键映射到键盘事件。

🎯 核心特性

🎮 广泛的手柄支持 - 兼容 Xbox、PlayStation、Nintendo Switch 等主流游戏手柄
📋 灵活的配置管理 - 三种配置获取方式：使用现有配置、导入外部配置、创建新配置
⚡ 高性能映射 - 响应延迟 < 5ms
🐛 调试模式 - 详细的事件日志便于诊断测试
🎯 多模式支持 - 支持自定义按键映射和多个映射模式切换
🌈 友好的 CLI 界面 - 使用 inquire 库提供直观的交互式菜单

🚀 快速开始

安装

假设你已安装 Rust 1.85+

# 从源码编译

git clone https://github.com/osynicite/osynic_pad

cd osynic_pad

cargo build --release


# 运行程序

./target/release/osynic-pad

或直接使用 cargo install：

cargo install osynic_pad

基本使用

启动程序后，会自动弹出交互式菜单：

1️⃣ 配置选择步骤

🎮 Osynic Pad 配置选择

请选择配置来源:
→ 📂 使用现有配置
  📥 导入配置（从指定位置）
  ✨ 新建配置（交互式）

三种选择说明：

📂 使用现有配置 - 选择 configs/ 目录下已有的配置文件
📥 导入配置 - 从任意位置导入 JSON 配置文件（自动复制到项目）
✨ 新建配置 - 交互式创建新配置文件

2️⃣ Debug 模式选择

🐛 启用 Debug 模式? (y/n)

3️⃣ 开始映射

配置完成后，程序即开始监听手柄输入，将按键映射到键盘事件。

⚙️ 配置文件格式

配置文件放在 configs/ 目录，采用 JSON 格式。

配置文件示例

{
  "default_mode": "Default",
  "mappings": {
    "Default": {
      "A": "Space",
      "B": "Escape",
      "X": "w",
      "Y": "s",
      "LB": "q",
      "RB": "e",
      "Start": "Return",
      "Back": "Tab"
    },
    "Alternative": {
      "A": "z",
      "B": "x",
      "X": "c",
      "Y": "v"
    }
  }
}

支持的按键

手柄按键

A, B, X, Y - 四个主要按键
Start, Back - 开始和返回按键
LB, RB - 左右 bumper
LT, RT - 左右 trigger（模拟量，转化为离散值）
LS, RS - 左右摇杆按键
DPadUp, DPadDown, DPadLeft, DPadRight - 方向键

键盘输出

支持所有标准键盘按键，如：a-z, 0-9, Space, Return, Escape 等。

📚 库的使用

将 osynic_pad 作为库集成到你的 Rust 项目：

[dependencies]

osynic_pad = "0.1.0"

tokio = { version = "1.51", features = ["sync", "rt-multi-thread"] }

代码示例

use osynic_pad::{Config, GamepadMapper, MappingMode};
use std::sync::Arc;
use tokio::sync::Mutex;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 加载配置
    let config = Config::load_from_path(&"configs/my_config.json".into())?;
    
    // 创建键盘输入句柄
    let enigo = Arc::new(Mutex::new(
        enigo::Enigo::new(&enigo::Settings::default())?
    ));
    
    // 创建映射器
    let mapper = Arc::new(GamepadMapper::new(
        config,
        enigo,
        MappingMode::Default,
        false, // debug 模式
    ));
    
    // 现在可以使用 mapper 处理手柄事件...
    Ok(())
}

🏗️ 项目结构

osynic_pad/
├── src/
│   ├── lib.rs          # 库入口
│   ├── main.rs         # CLI 二进制程序入口
│   ├── cli.rs          # 交互式 CLI 菜单
│   ├── config.rs       # 配置文件处理
│   ├── events.rs       # 手柄事件定义
│   ├── mapper.rs       # 核心映射逻辑
│   └── error.rs        # 错误类型定义
├── configs/            # 配置文件目录
│   ├── pad_config.json
│   └── ...
├── examples/           # 使用示例
└── Cargo.toml         # 项目配置

📚 API 文档

主要类型和函数

Config - 配置文件结构
GamepadMapper - 手柄事件映射器
MappingMode - 映射模式枚举
PadEvent - 手柄事件类型

详细 API 文档可通过 cargo doc --open 查看。

🔧 开发

前置要求

Rust 1.85.0 或更高版本
Cargo

本地构建

cargo build

cargo build --release

运行测试

cargo test

代码检查

cargo clippy

cargo fmt

🤝 贡献

欢迎提交 Issue 和 Pull Request！

请确保：

遵循 Rust 社区编码规范
通过所有 clippy 检查
代码已格式化

📜 协议

本项目采用 MIT License 开源，详见 LICENSE 文件。

🙏 致谢

本项目依赖以下优秀的开源库：

gilrs - 手柄输入
enigo - 键盘输出模拟
inquire - 交互式 CLI
serde - 序列化/反序列化
tokio - 异步运行时

📞 联系方式

提交问题：GitHub Issues
项目地址：GitHub Repository

osynic_pad 0.1.0