# trainerforge-3d

**Repository Path**: kill-life/trainerforge-3d

## Basic Information

- **Project Name**: trainerforge-3d
- **Description**: TrainerForge-3D 在 Linux 上为 Wine/Proton 游戏提供一键启动风灵月影（FLiNG）修改器与 UU3D 3D 模式自动部署注入。右键托盘图标，选择游戏，即刻到位。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/kill-life/trainerforge-3d
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="trainerforge3d/resources/icon.png" width="140" alt="TrainerForge-3D Icon">
  <h1>TrainerForge-3D</h1>
  <p>
    <strong>复合游戏修改器 + UU3D 3D 自动部署注入启动器</strong><br>
    <em>Composite Game Trainer &amp; UU3D 3D Auto-Deploy Launcher for Linux · Wine · Proton</em>
  </p>
  <p>
    <a href="#特性">特性</a> ·
    <a href="#proton-版本要求">Proton 要求</a> ·
    <a href="#快速开始">快速开始</a> ·
    <a href="#安装">安装</a> ·
    <a href="#使用方法">使用</a> ·
    <a href="#uu3d-资源">UU3D 资源</a> ·
    <a href="#配置">配置</a> ·
    <a href="#常见问题">FAQ</a> ·
    <a href="#协议">协议</a>
  </p>
  <p>
    <img src="https://img.shields.io/badge/platform-linux-blue?style=flat-square&logo=linux" alt="Platform">
    <img src="https://img.shields.io/badge/python-3.8+-green?style=flat-square&logo=python" alt="Python">
    <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" alt="License">
    <img src="https://img.shields.io/badge/status-alpha-red?style=flat-square" alt="Status">
    <img src="https://img.shields.io/badge/packaging-deb%20%7C%20rpm%20%7C%20appimage-blue?style=flat-square" alt="Packaging">
  </p>
</div>

---

> **TrainerForge-3D** 在 Linux 上为 Wine/Proton 游戏提供**一键启动风灵月影（FLiNG）修改器**与 **UU3D 3D 模式自动部署注入**。右键托盘图标，选择游戏，即刻到位。

它完整继承了 TrainerForge 的成熟交互，并引入独立的 **UU3D 3D 模块**：下载校验注入器、按游戏放置 3D 配置、自动注入——全流程在一个优雅的界面内完成。

## 🧪 Proton 版本要求

> **⚠️ 重要**：本程序在 **Proton 10-34** 下稳定运行（推荐）。使用 **Proton 11-2** 会导致 **修改器与 UU3D 无法正常使用**，请务必避免。

<div align="center">
  <img src="https://img.shields.io/badge/Proton%2010--34-%E7%A8%B3%E5%AE%9A%E8%BF%90%E8%A1%8C-green?style=for-the-badge&logo=linux&logoColor=white" alt="Proton 10-34 稳定运行" height="45">
  &nbsp;&nbsp;
  <img src="https://img.shields.io/badge/Proton%2011--2-%E4%BF%AE%E6%94%B9%E5%99%A8%20%2F%20UU3D%20%E5%BC%82%E5%B8%B8-red?style=for-the-badge&logo=linux&logoColor=white" alt="Proton 11-2 异常" height="45">
</div>

| Proton 版本 | 状态 |
|:---:|:---:|
| ✅ **Proton 10-34** | **稳定运行（推荐）** |
| ❌ **Proton 11-2** | **修改器 / UU3D 异常** |
| ❌ Proton Experimental | **修改器 / UU3D 异常** |

## ✨ 特性

- **🖱 一键启动** — 托盘图标 → 选择游戏 → **风灵月影（FLiNG）修改器** / UU3D 注入器自动在正确的 Proton prefix 中启动
- **🥽 UU3D 3D 模块** — 自动下载 + 校验 + 解压 UU3D 注入器，按游戏放置 3D 模式配置并注入
- **🔍 自动检测** — Steam（原生 / Flatpak / Snap）、Proton、Wine、UMU、compatdata 全自动发现
- **⚙️ 关键设置** — 直接编辑 UU3D 下载链接 / 加速镜像 / sha256 校验，版本信息随链接实时同步
- **🎨 三款主题** — 暗色 / 亮色 / Mac 紫，实时切换
- **🌐 中英文切换** — 即时生效，无需重启
- **📦 自包含设计** — 所有配置与数据存于安装目录；卸载零残留
- **🛡 单实例锁** — 重复启动自动聚焦已有窗口
- **🌍 跨发行版** — .deb 包，用户级安装至 `~/.local`

## 🚀 快速开始

### 前置条件

1. 系统已安装 **Steam**（[官网下载](https://store.steampowered.com/about/) 或 `sudo apt install steam`）
2. Steam → 设置 → 兼容性 → 启用 **"为所有产品启用 Steam Play"** → 选择 **Proton 10-34**
3. 安装唯一硬依赖 `python3-pyqt5`

> **Proton 版本**：请使用 **Proton 10-34**，详见 [Proton 版本要求](#proton-版本要求)。

### 安装

```bash
# 安装 .deb 包
sudo dpkg -i trainerforge-3d_*.deb
trainerforge-3d

# 或从源码运行
git clone https://gitee.com/kill-life/trainerforge-3d.git
cd trainerforge-3d
python3 -m trainerforge3d
```

## 📦 安装

| 格式 | 命令 | 适用环境 |
|--------|---------|---------|
| **.deb** | `sudo dpkg -i trainerforge-3d_*.deb` | Ubuntu、Debian、Mint、Pop!_OS |
| **.rpm** | `sudo rpm -i trainerforge-3d-*.rpm` | Fedora、RHEL、OpenSUSE |
| **AppImage** | `chmod +x trainerforge-3d-*.AppImage && ./trainerforge-3d-*.AppImage` | 任意 Linux |
| **源码** | `python3 -m trainerforge3d` | 任意 Linux |

> 全部产物在 `dist/`（含 `SHA256SUMS` 校验清单）。AppImage 无需安装，直接运行；数据自动落于 `~/.config` / `~/.local/share`，卸载零残留。

唯一硬依赖 `python3-pyqt5`，主流发行版均预装：

```bash
# Ubuntu/Debian
sudo apt install python3-pyqt5

# Fedora
sudo dnf install python3-qt5

# Arch
sudo pacman -S python-pyqt5
```

## 🎮 使用方法

### 1. 添加游戏

- 打开 TrainerForge-3D（系统托盘图标）
- 点击 **＋ 添加**
- 填写：
  - **游戏进程名** — Windows `.exe` 文件名（如 `Palworld-Win64-Shipping.exe`）
  - **修改器路径** — 风灵月影（FLiNG）修改器 .exe 完整路径
  - **UU3D 配置包** — UU3D 3D 预设 .zip 完整路径
  - **Proton Prefix** — 点击自动检测，或从列表选择
  - **Proton Wine** — 点击自动查找

### 2. 启动修改器 / UU3D 注入

- **先在 Steam/Lutris 中启动游戏**
- 右键 TrainerForge-3D 托盘图标
- 选择 `▶ 启动修改器 — 游戏名` 或 `▶ 注入 UU3D — 游戏名`
- 目标进程在同一个 Proton prefix 中被唤醒并注入

> **⚠️ 特别强调 —— UU3D 使用规范：务必设置 Steam 启动参数 `-nohmd`**
>
> 按 UU3D 官方使用规范，使用 UU3D 3D 注入前，**必须**在 Steam 游戏属性中为对应游戏设置**启动选项**为：
>
> ```
> -nohmd
> ```
>
> 即 **Steam → 游戏 → 属性 → 通用 → 启动选项** 填入 `-nohmd`（见示例图 `steam_config.png`）。
>
> 该参数用于**禁用虚幻引擎的头戴显示（HMD）初始化**，避免与 UU3D 的 3D 注入产生冲突。**未设置时 UU3D 可能无法正常出 3D 或注入失败**，这是 UU3D 使用中最高优先级的注意事项，请务必在部署 UU3D 前完成配置。

### 3. 部署 UU3D 3D 环境

在 **UU3D-3D 标签页** 中：

- **安装注入器** — 在线下载（自动校验 sha256）或本地导入
- **放置 3D 配置** — 将 UU3D 配置文件写入游戏对应的 prefix 目录
- **安装 / 卸载 .NET** — 一键管理游戏运行所需的 .NET Desktop Runtime 6

## 🥽 UU3D 资源

<table>
<tr><th w="34%">资源</th><th>说明</th><th>链接</th></tr>
<tr><td><b>UU3D</b></td><td>虚幻引擎通用 3D 注入器（GitHub）</td><td><a href="https://github.com/oneup03/UU3D#unreal-universal-3d">github.com/oneup03/UU3D</a></td></tr>
<tr><td><b>UU3D-Profiles</b></td><td>虚幻引擎游戏 3D 预设文件（开发者）</td><td><a href="https://github.com/oneup03/UU3D-Profiles">github.com/oneup03/UU3D-Profiles</a></td></tr>
<tr><td><b>UU3D 专用预设补丁</b></td><td>虚幻引擎游戏 UU3D 专用 3D 预设补丁（B站 UP 游戏老酱）</td><td><a href="https://pan.baidu.com/s/1s7QKKHexd3KlnFIpCS3UYQ?pwd=b926">百度网盘</a></td></tr>
</table>

> 💡 **提示**：`UU3D.zip` 直链可从 [UU3D Releases](https://github.com/oneup03/UU3D/releases) 获取，填入设置页的下载链接即可。

> 📖 **参数参考**：UU3D 菜单各参数（渲染方法、输出模式、深度/收敛/视场角、准星、GUI、头部跟踪等）的准确中文说明见 **[UU3D 使用参数指南](docs/UU3D使用参数指南.md)**（[英文版](docs/UU3D-Usage-Parameters-Guide.md)）。

## 🔧 配置

所有配置存储在 `<安装目录>/config/config.json`（自包含）。示例：

```json
{
  "entries": [],
  "u3d_entries": [
    {
      "game_exe": "Palworld-Win64-Shipping.exe",
      "profile_zip": "/games/Palworld/UU3D/Palworld-Win64-Shipping.zip",
      "prefix": "/home/user/.local/share/Steam/steamapps/compatdata/1623730/pfx/",
      "proton_wine": "/home/user/.local/share/Steam/steamapps/common/Proton - Experimental/files/bin/wine",
      "inject_mode": "auto",
      "uu3d_version": "nightly-00036"
    }
  ],
  "settings": {
    "theme": "dark",
    "language": "zh",
    "uu3d_mirror": "https://gh.xmly.dev/",
    "uu3d_zip_url": "",
    "uu3d_sha256": "",
    "uu3d_pin_label": "nightly-00036-ada23c259d5e9edb1db94a0492286c4505ce4858"
  }
}
```

### UU3D 版本管理

- **设置页** — 编辑 UU3D 下载链接与镜像，`UU3D当前版本` 随链接实时同步
- **UU3D-3D 标签页** — 扫描 / 刷新已安装版本，可为每个游戏指定不同的 UU3D 版本
- **重命名 / 卸载** — 按版本卸载注入器，清理零残留

## ❓ 常见问题

**Q: 修改器没有启动？**
A: 确认游戏已在 Steam/Lutris 中运行，且 Proton Prefix 与 Wine 路径检测正确。参考日志面板中的诊断信息。

**Q: 修改器或 UU3D 无法正常工作？**
A: 请检查 Proton 版本，**务必使用 Proton 10-34**；Proton 11-2 会导致异常。若为 **UU3D 3D 无法出图或注入失败**，请先确认已在 Steam 游戏属性的**启动选项**中填入 `-nohmd`（UU3D 使用规范强制要求，详见 [第 2 步 UU3D 注入](#2-启动修改器--uu3d-注入)）。

**Q: UU3D 下载失败？**
A: 设置页可更换加速镜像（如 `https://gh.xmly.dev/`），或改用"本地导入"使用已下载的 UU3D.zip。

**Q: 卸载会留下什么？**
A: 不会。所有配置与数据都在 `~/.local/trainerforge-3d/`，通过系统包管理器或卸载按钮即可干净移除。

## 📄 协议

MIT — 详见 [LICENSE](LICENSE) 文件。

---

<div align="center">
  <img src="trainerforge3d/resources/icon.png" width="64" alt="TrainerForge-3D Icon">
  <p><sub>Made for Linux gamers who want their trainers &amp; 3D without the hassle.</sub></p>
</div>