# ffjoy

**Repository Path**: mugongdaren/ffjoy

## Basic Information

- **Project Name**: ffjoy
- **Description**: 一个自动消消乐项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HT丶木公的翻翻乐

自动识别并完成屏幕上的卡片翻翻乐游戏。

## 功能特性

- 屏幕区域选择
- 动态卡片特征学习
- 自动匹配和消除
- 自动开始下一局
- 可暂停/继续/停止
- 速度调节
- 实时日志显示

## 环境要求

- Python 3.8 或更高版本
- Windows / macOS / Linux 操作系统

## 快速使用（无需安装Python）

如果你不想安装Python环境，可以直接使用打包好的exe文件：

1. 下载 `HT丶木公的翻翻乐.exe`（约100-150MB）
2. 双击运行即可

**如何打包成exe？** 查看 [BUILD.md](BUILD.md) 了解详细打包步骤。

## 从零开始安装

### 1. 安装Python（如果还没有）

**Windows:**
1. 访问 [python.org](https://www.python.org/downloads/)
2. 下载 Python 3.8+ 安装包
3. 运行安装程序，**勾选"Add Python to PATH"**
4. 验证安装：打开命令提示符，输入 `python --version`

**macOS:**
```bash
# 使用 Homebrew 安装
brew install python3
```

**Linux:**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip

# CentOS/RHEL
sudo yum install python3 python3-pip
```

### 2. 下载项目

```bash
# 如果有git
git clone <项目地址>
cd ffjoy

# 或者直接下载ZIP解压后进入目录
```

### 3. 安装依赖

```bash
pip install -r src/requirements.txt
```

如果遇到权限问题，使用：
```bash
pip install --user -r src/requirements.txt
```

### 4. 启动程序

```bash
python src/main.py
```

或者在Windows上：
```bash
python src\main.py
```

### 5. 使用步骤

1. **选择游戏区域**
   - 点击"选择游戏区域"按钮
   - 屏幕会显示半透明灰色覆盖层
   - 用鼠标拖拽框选卡片游戏区域
   - 松开鼠标完成选择

2. **设置网格参数**
   - 根据游戏实际情况设置行数和列数（默认4x4）
   - 例如：4行4列表示16张卡片

3. **设置下一局按钮**
   - 点击"设置下一局按钮"
   - 屏幕会显示半透明灰色覆盖层
   - 点击游戏中"下一局"或"重新开始"按钮的位置

4. **调整速度（可选）**
   - 拖动"点击延迟"滑块调整速度
   - 默认500ms，范围100-2000ms
   - 延迟越小速度越快，但可能影响识别准确度

5. **开始游戏**
   - 点击"开始"按钮
   - 程序会自动点击卡片、识别、匹配和消除
   - 可随时点击"暂停"或"停止"

6. **查看日志**
   - 底部日志区域会实时显示操作记录
   - 包括点击位置、匹配结果、消除进度等

## 技术栈

- Python 3.8+
- Tkinter (GUI)
- OpenCV (图像处理)
- PyAutoGUI (屏幕操作)
- Pillow (图像格式转换)
- NumPy (数值计算)

## 项目结构

```
src/
├── main.py              # 程序入口
├── ui/                  # UI模块
│   ├── main_window.py   # 主窗口
│   └── region_selector.py # 区域选择
├── core/                # 核心逻辑
│   ├── screen_capture.py   # 屏幕捕获
│   ├── image_matcher.py    # 图像匹配
│   ├── game_state.py       # 游戏状态
│   ├── click_controller.py # 点击控制
│   └── game_controller.py  # 游戏控制器
└── utils/               # 工具模块
    └── config.py        # 配置管理
```

## 注意事项

- 需要屏幕截图和鼠标控制权限
- 适用于固定网格布局的消消乐游戏
- 建议在1920x1080或更高分辨率下使用
- 首次运行可能需要安装较大的依赖包（OpenCV约100MB）

## 常见问题

**Q: 提示"No module named 'cv2'"？**
A: OpenCV未安装成功，尝试：`pip install opencv-python`

**Q: 提示"No module named 'tkinter'"？**
A: Tkinter未安装（Linux系统）：`sudo apt install python3-tk`

**Q: 程序无法点击或截图？**
A: 检查是否授予了屏幕录制和辅助功能权限（macOS需要在系统偏好设置中授权）

**Q: 识别不准确？**
A: 尝试调整相似度阈值，或确保卡片视觉差异明显

**Q: 如何停止程序？**
A: 点击"停止"按钮，或直接关闭窗口