# GXCL

**Repository Path**: shenmo7192/gxcl

## Basic Information

- **Project Name**: GXCL
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-20
- **Last Updated**: 2026-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GXCL

**GXDE Crafting Launcher** —— 面向 GXDE 桌面的原生 Minecraft 启动器。

GXCL 使用 C++ / Qt 6 / [DTK2Widget-Qt6](https://gitee.com/GXDE-OS/dtk2widget-qt6) 编写。功能可对照 HMCL 进行规划，再以 GXCL 自己的方式实现；微软登录与 LittleSkin 账户流程参考 [LMAML](https://xphost008.github.io/lmaml/)，并以官方协议文档为准。当前仅开发 Linux，不实现地区/IP 检测或下载封锁。

> 当前状态：**v0.1 开发中**。M0（项目基座）、M1（DTK2 UI 壳 + 真实版本清单）、M2（实例扫描与管理）、M3（下载安装，mock 验证）、M4（启动，fake Java + ARM64 原生库验证）与 M5 基础设置已实现，真实 1.20.1 下载/启动验证待确认。
> 路线图与里程碑见 [ROADMAP.md](ROADMAP.md)。

---

## 界面预览

> 使用 `--demo` 示例数据截取；默认浅色主题，最后一张为深色主题。

<p align="center">
  <img src="docs/screenshots/home.png" width="49%" alt="首页">
  <img src="docs/screenshots/downloads.png" width="49%" alt="下载页">
</p>
<p align="center">
  <img src="docs/screenshots/instances.png" width="49%" alt="实例管理">
  <img src="docs/screenshots/accounts.png" width="49%" alt="账户">
</p>
<p align="center">
  <img src="docs/screenshots/settings.png" width="49%" alt="设置">
  <img src="docs/screenshots/install.png" width="49%" alt="安装进度">
</p>

<p align="center">
  <img src="docs/screenshots/dark-home.png" width="80%" alt="深色主题">
</p>

## 当前实现（M0–M4 + M5 基础设置）

- **DTK2 原生界面**：`DMainWindow` + 侧栏 + 六个页面（首页、实例、下载、账户、设置、安装预览）；
- **主题**：跟随系统 / 浅色 / 深色，`DApplication` 主题与调色板同步；
- **真实版本清单**：Mojang 版本清单获取、本地缓存、正式版/快照/远古筛选与搜索（919 个版本、103 个正式版）；
- **离线账户**：本地 UUID 生成、添加/删除/切换、头像预览；
- **真实实例管理**：扫描 `<游戏目录>/versions`、解析版本 JSON、识别 Fabric/Quilt/Forge/NeoForge、读取客户端 jar 与 Java 要求；
- **实例操作**：导入其他 .minecraft 版本目录、复制、删除、重命名显示名、设为当前；
  - 导入目前只复制 `versions/<id>` 版本目录，共享库/资源文件由 M3 的安装与修复流程补齐；
- **游戏目录**：可在设置中切换，实例列表与首页/侧栏实时刷新；
- **Java 探测**：扫描 JAVA_HOME、/usr/lib/jvm、PATH 与 GXCL 运行时目录，解析 release 文件；
- **设置**：下载源、并发数、游戏目录、Java 运行时探测/手动选择与重新检测、最大内存、JVM 参数、窗口大小；
- **下载器**：并发下载、官方/BMCLAPI 候选回退、`.part` 断点续传、SHA-1 校验、失败重试；
- **原版安装**：版本 JSON、客户端 jar、库、natives 文件、资源索引与资源对象、logging 配置；磁盘空间检查；
- **修复安装**：重复执行安装会跳过 SHA-1 正确的文件并补齐缺失/损坏文件；
- **安装 UI**：安装进度、阶段状态、实时 MB/百分比、日志、取消与失败重试；
- **启动**：Java 选择、版本继承合并、规则过滤、JVM/游戏参数模板、classpath、natives 解压、离线账户占位符；
- **ARM64 修补**：Linux ARM64 下将 LWJGL 3.3.1 及更早版本提升到 3.3.2，并替换为 `natives-linux-arm64`（Maven Central），启动前自动补齐；
- **进程与日志**：QProcess 启动、stdout/stderr 合并、游戏日志窗口、退出码提示、启动日志写入 `<gameDir>/logs/`；
- **崩溃报告**：非零退出时自动查找 `<gameDir>/crash-reports/crash-*.txt`，在游戏日志中显示路径；
- **工程化**：CMake、Qt Test（4 组）、日志、desktop/AppStream/debian 打包骨架、截图脚本。

> M3 已用本地 mock 仓库完成安装/修复/续传/镜像回退测试；M4 已用真实 JDK 启动 fake Java 主类，并真实下载 LWJGL 3.3.2 ARM64 原生库、解压 `.so`、以补丁后的 classpath 启动，验证参数构建、进程、日志与退出码。
> 真实 Minecraft 下载安装（约 1 GB）与真实客户端启动尚待确认后验证。
> 尚不可用的功能：Java 自动下载/管理、版本隔离、代理与完整 M5 设置；M6 加载器与模组管理。
> 交接说明见 [HANDOFF.md](HANDOFF.md)。

## 特性规划

- [x] 项目基座、构建、测试、打包骨架（M0）
- [x] DTK2 UI 壳、页面路由、主题、真实版本清单（M1）
- [x] 离线账户界面
- [x] 实例扫描、游戏目录管理、导入/复制/删除/重命名（M2）
- [x] 原版下载安装与 SHA-1 校验（M3，mock 验证）
- [x] 启动游戏、离线账户、ARM64 修补、日志（M4，fake Java 验证）
- [ ] Java 管理与完整设置（M5，基础游戏设置已完成）
- [ ] 微软登录、LittleSkin 外置登录（v0.2）
- [ ] Fabric / Quilt / Forge / NeoForge、Modrinth（v0.3）

## 构建

### 依赖（Debian / GXDE）

```bash
sudo apt install build-essential cmake ninja-build pkg-config \
    qt6-base-dev qt6-svg-dev qt6-tools-dev libarchive-dev \
    libdtk2widget6-dev librsvg2-dev
```

> `libdtk2widget6-dev` 会带入 DTK6 Core / Log 等依赖；`debhelper` 仅在打包阶段需要。

### 构建 Debian 包

仓库根目录包含标准 `debian/` 目录，可使用 `dpkg-buildpackage` 生成适用于当前架构的 `.deb`：

```bash
sudo apt install debhelper-compat devscripts
sudo mk-build-deps -i -r debian/control
dpkg-buildpackage -us -uc -b
sudo apt install ../gxcl_0.1.0-1_$(dpkg --print-architecture).deb
```

构建产物写入仓库上级目录。也可先用 `dpkg-checkbuilddeps` 检查依赖；构建依赖清单见 `debian/control`。

### 编译运行

```bash
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/gxcl
```

### 开发模式

```bash
# 示例实例 / 账户
./build/gxcl --demo

# 以深色主题启动
./build/gxcl --demo --theme dark

# 执行单元测试
ctest --test-dir build --output-on-failure

# 生成全部页面截图（Xvfb，无需窗口管理器）
./tools/screenshot.sh ./build/gxcl
THEME=dark ./tools/screenshot.sh ./build/gxcl
```

可用页面：`home`、`instances`、`downloads`、`accounts`、`settings`、`install`。

单页截图：

```bash
xvfb-run -a ./build/gxcl --demo --page home \
    --screenshot /tmp/gxcl-home.png --screenshot-delay 2500
```

## 目录结构

```text
src/app       应用初始化、配置、日志、演示数据
src/core      网络、版本元数据、离线账户、路径
src/ui        主窗口、侧栏、页面、通用控件
src/resources 图标、qrc
tests         Qt Test 单元测试
tools         截图脚本
packaging     desktop、AppStream、debian 骨架
docs          设计与截图
```

## 配置与日志

| 用途 | 路径 |
|---|---|
| 配置 | `~/.config/gxcl/config.json` |
| 实例元数据 | `<游戏目录>/versions/<id>/gxcl-instance.json` |
| 缓存 | `~/.cache/gxcl/` |
| 日志 | `~/.local/state/gxcl/logs/gxcl.log` |

## 说明

- GXCL 是非官方启动器，与 Mojang / Microsoft 无关联。
- 不随包分发 Minecraft 游戏资源；游戏文件在用户操作时从官方或镜像下载。
- 不实现地区检测、IP 查询或下载封锁；镜像仅作为用户可选项。
- 本项目使用 GPL-3.0 许可证（`LICENSE`）。
- 作者：shenmo `<shenmo@spark-app.store>`