项目概览
Ark-Pets（明日方舟桌宠）是一个基于 Java 开发的跨模块桌面应用程序，用于将《明日方舟》的 Spine 角色模型以桌面宠物（Desktop Pet）的形式运行在 Windows 桌面上，并提供启动器图形界面、模型库下载、模拟平面重力场等完整能力。
目的与范围（Purpose and Scope）
本页面是整个 Wiki 的入口页，旨在为读者建立对 Ark-Pets 的整体认知：
- 本页覆盖：项目的定位与功能边界、源码模块划分（
core/desktop）、系统总体架构、典型使用流程、用户可见的运行行为与特性清单、运行环境与技术栈约束。 - 本页不覆盖（留给兄弟页面）：桌宠运行时内部实现的逐行走读（如
ArkPets、ArkChar的渲染与行为状态机）、启动器 JavaFX 界面细节、配置文件ArkConfig的完整键值解析、命令行启动、自定义模型导入、遥测机制等专题。相关内容将在各自的目录页中展开，本文末尾的「相关链接」一节提供导航。
说明：本页面向首次接触本仓库的开发者与维护者，是"读代码之前先读的一页"。
概述（Overview）
项目定位
Ark-Pets 是一个 GPL-3.0 协议开源的明日方舟桌宠项目，仓库地址为 isHarryh/Ark-Pets，当前文档对应 v3.x 分支。项目的核心价值可以概括为三条主线：
- 模型启动：支持将《明日方舟》角色模型作为桌宠启动，包括干员基建小人（含时装）、干员动态立绘（含时装）、敌方战斗小人三类模型。
- 启动器 GUI：提供图形化界面，用于浏览模型（按名称、拼音、时装品牌搜索或按类别筛选）、从社区维护的模型库联网下载、以及调整桌宠的行为与显示设置。
- 行为与物理模拟：桌宠不仅渲染动画，还模拟游戏内角色行为（行走、坐下、躺下、戳一戳、特殊基建动作），并实现了模拟平面重力场（自由落体、拖拽到扩展屏、站立在打开窗口的边缘上）。
目标用户与运行环境
- 目前仅支持 Windows 7 及以上的图形操作系统；macOS 与 Linux 支持处于开发阶段（
README.md明确声明）。 - 发布形态有三种：
ArkPets-Setup.exe安装包（功能完整）、zip免安装压缩包、jar版程序文件（需要本机存在JDK17运行环境，且无法使用开机自启动功能）。 - 项目主语言为 Java（GitHub Top Language 徽章标注为 Java）。
关键概念与术语
| 术语 | 含义 |
|---|---|
| 桌宠（Desktop Pet） | 运行在桌面上的透明窗口角色，受重力场约束、可交互 |
| 启动器（Launcher） | desktop 模块中的 JavaFX 图形界面程序，负责模型检索与设置 |
| 模型库（Models Repo） | 由社区维护、从互联网下载的模型集合，参见关联项目 Ark-Models |
| 手动模式 | 托盘菜单开关，启用后用方向键控制桌宠移动与切换动作 |
| 透明模式 | 托盘菜单开关，屏蔽桌宠与鼠标的一切交互（鼠标穿透到下层窗口） |
| 模拟平面重力场 | 桌宠的自由落体、跨屏拖拽、站立窗口边缘等物理行为的统称 |
架构（Architecture）
从仓库源码目录可以确认，Ark-Pets 采用双模块组织：core 与 desktop，两者源码根均为 src/cn/harryh/arkpets/（包名 cn.harryh.arkpets）。
上述图中每个节点都对应仓库中真实存在的类文件（详见 desktop/src/cn/harryh/arkpets 与 core/src/cn/harryh/arkpets 两个包目录）。需要说明的是：
core模块承载桌宠运行时本体：ArkPets、ArkChar、ArkConfig、Const四个类构成桌宠进程的核心（从命名与模块归属可见其职责：运行时入口 / 角色实体 / 配置 / 常量）。本页只定位它们的角色，其内部实现走读属于兄弟页面内容。desktop模块承载启动器与桌面端集成：DesktopLauncher、EmbeddedLauncher两个入口类分别对应不同启动形态；ArkHomeFX是 JavaFX 图形主界面；utils子包提供命令行参数解析（ArgPending）、对话框（DialogComposer）、FXML 辅助（FXMLHelper）、通用 GUI 组件（GuiComponents）与错误上报（SentryHelper）。- 虚线表示非编译期依赖的外部资源：模型库下载、Mirror 酱 CDN 接入（
README.md记载自 v3.9 版本开始接入）。
桌宠运行期行为架构
从用户视角，一个桌宠从"选中"到"运行"再到"退出"的完整链路如下（依据 README.md 描述的使用流程与托盘行为整理）：
这张流程图概括了 Ark-Pets 在运行期最核心的三类行为来源：物理系统（重力场）、交互系统（鼠标戳一戳、托盘菜单）、行为系统（空闲动作状态机）。三者共同决定了桌宠的观感与体验，也是 core 模块内部实现的主体。
核心功能与特性
以下是 README.md 中"实现的功能"一节的原始表述（用于说明项目对自身的定位，保留原文以避免转述失真）：
- 支持将《明日方舟》角色模型作为桌宠启动。 现已支持的模型类型包括：干员基建小人（含时装）；干员动态立绘（含时装）；敌方战斗小人。
- 启动器提供图形用户界面以便浏览模型和调整各种设置。 可以按名称、拼音、时装品牌搜索，或按类别筛选以查找模型；可以从互联网中下载由社区维护的模型库；可以自定义桌宠的动作交互、部署位置和物理参数等行为设置；可以自定义桌宠的图像缩放、最大帧率和窗口边界等显示设置。
- 支持模拟游戏内干员基建小人的行为。 支持行走、坐下和躺下的动作；能够被鼠标交互以执行戳一戳动作；拥有特殊基建动作的干员，有概率触发这类动作。
- 支持模拟游戏内敌方小人的行为。 拥有行走动作的敌人能够行走；拥有攻击动作的敌人能够被鼠标交互。
- 实现了模拟平面重力场。 桌宠支持自由落体等物理现象；桌宠可以被拖拽到扩展显示屏上；桌宠可以站立在打开的窗口的边缘上。
- 实现了系统托盘的菜单。 右键托盘图标或者桌宠本体均可弹出菜单；菜单可用于开启手动模式和启用透明模式；菜单可用于切换多形态角色的形态；菜单可用于退出启动器或单个桌宠；启动器运行时，已启动的桌宠将被整合到一个托盘中；启动器若没有运行，每个桌宠将分别创建自己的托盘。
- 支持开机自启动等更多特性。
Source: README.md
桌宠侧特性
| 特性 | 说明 | 设计意图 |
|---|---|---|
| 开机自启动 | 启动器"选项"页可设置；下次开机自动生成最后一次启动的桌宠 | 减少重复配置成本；注意 jar 版本无法使用此功能 |
| 手动模式 | 托盘菜单开启后，用左右方向键控制桌宠移动，上下方向键切换动作 | 为演示 / 截图 / 调试场景提供可控性 |
| 透明模式 | 屏蔽桌宠与鼠标的一切交互，鼠标操作穿透到下层窗口 | 解决游戏、观看视频时误触桌宠的问题 |
| 下边界距离 | 在"行为"页面手动设置任务栏高度 | 兜底方案：部分电脑上任务栏检测失败、桌宠沉入任务栏 |
| 高亮描边与阴影 | 复现游戏中基建系统的角色选中特效；阴影提供立体感 | 提供视觉保真度，但可在"选项"中禁用以降低性能消耗（性能开关的典型例子） |
启动器侧特性
- 公告栏：侧边栏"公告"按钮打开，显示更新日志等帮助信息；每次启动器启动时若发现未读的重要公告会自动弹出 —— 这是一个"重要信息必达"的推送通道。
- 模型库联网下载与更新：模型页面"模型库管理"面板支持下载模型库与检查更新。
- 软件更新：选项页面可检查并安装软件更新。
- Mirror 酱接入：自 v3.9 起接入 Mirror 酱，提供高速内容下载体验。
Source: README.md
高级用法与分发形态
README.md 的"高级用法"一节列出了三种非默认使用方式，对本项目的架构理解有直接指导意义：
- 下载
zip版程序压缩包解压，实现免安装使用。 - 电脑上存在
JDK17运行环境时，下载jar版程序文件直接运行（无法使用开机自启动）。 - 需要用直播流软件捕捉桌宠窗口时，在启动器"选项"页禁用"桌宠作为后台程序启动"。
第 3 点揭示了一个重要架构事实：桌宠窗口默认以后台程序方式启动，因此 OBS 等捕捉工具默认抓不到它，必须显式禁用该选项。这是"桌宠不干扰前台工作"设计目标的直接体现。
Source: README.md
使用流程（Quick Start）
README.md 给出的官方快速上手步骤如下（这是理解用户与系统交互入口的最短路径）：
- 前往 Releases 页面下载最新的
ArkPets-Setup.exe安装包。 - 运行安装包完成安装，打开 ArkPets 启动器。
- 首次使用需下载模型文件：在启动器"模型"页面的"模型库管理"面板点击"下载模型"按钮。
- 在"模型"页面检索并选中想要作为桌宠启动的角色，点击左下角"启动"按钮生成桌宠。
官方还给出三条补充提示：
- 关闭桌宠：右键单击桌宠或系统托盘中的 ArkPets 图标，选择"退出"。
- 软件内下载模型失败时的兜底：访问 ArkModels 模型仓库 手动下载模型压缩包，在"模型库管理"面板点击"导入压缩包"按钮导入 —— 说明模型导入支持在线下载与本地压缩包导入双通道。
- 版本升级：从 v2.x 或 v3.x 升级到更高版本无需预先手动卸载，直接运行新版安装包即可。
Source: README.md
技术栈与生态
技术栈（从仓库可见证据）
| 层面 | 技术 | 证据来源 |
|---|---|---|
| 主语言 | Java | GitHub Top Language 徽章（README.md L15）；jar 版要求 JDK17 |
| 启动器 UI | JavaFX / FXML | desktop 模块存在 ArkHomeFX 类与 FXMLHelper 工具类 |
| 错误监控 | Sentry | desktop/src/cn/harryh/arkpets/utils/SentryHelper.java，另有独立文档 docs/Telemetry.md |
| 构建体系 | Gradle | 仓库根存在 *.gradle* 构建脚本（Grep 命中） |
| 持续集成 | GitHub Actions | README.md 中的 Build 徽章指向 build.yml 工作流 |
| 模型格式 | Spine 骨骼动画 | 关联项目 Ark-Models 描述为"明日方舟 Spine 模型库" |
关联与衍生项目
README.md 列出了与本项目的关联或衍生项目，理解它们有助于划清本项目的能力边界：
- isHarryh / Ark-Models：明日方舟 Spine 模型库 —— Ark-Pets 的模型数据来源，两者是"程序"与"数据"的分工关系。
- litwak913 / Ark-Pets-Integration：ArkPets 针对其他桌面系统的集成库。
- fuyufjh / Ark-Pets-Web：ArkPets 在网页渲染器上的独立实现。
- isHarryh / Ark-Unpacker：用于解包游戏资源的实用工具（模型生产链路的上游）。
- Aloento / SuperSpineViewer：用于查看 Spine 模型的实用工具。
Source: README.md
项目状态与路线图
README.md 明确列出的"下一步计划"（原文注明"以下内容可能在遥远的将来被实现"）：
- 国际化与响应布局
- 支持按需下载资源
- 支持干员语音功能
- 全面更新依赖库的版本
- 支持透明模式等配置的记忆
其中"按需下载资源"与"透明模式等配置的记忆"两条，分别指向当前架构中模型库整体下载与运行期状态不做持久化这两处已知的设计取舍。
Source: README.md
许可证与协作
- 许可证：GPL-3.0。原文约束："任何人都可以自由地使用和修改项目内的源代码，前提是要在源代码或版权声明中保留作者说明和原有协议，且使用相同的许可证进行开源。"
- 参与贡献：通过提交 Issues 参与贡献；提交前需确认议题不重复，并完整填写议题模板。
- 文档语言：项目官方声明"只支持中文文档"，英文用户需联系维护者。
Source: README.md
相关链接
仓库内文档：
- README.md — 项目主说明文档（本文的主要证据来源）
- CHANGELOG.md — 更新日志
- docs/FAQ.md — 常见问题解答
- docs/Telemetry.md — 遥测功能说明
- docs/CmdLine.md — 命令行启动说明
- docs/CustomModel.md — 自定义模型说明
- docs/Credits.md — 鸣谢和第三方库说明
关键源码入口：
- core/src/cn/harryh/arkpets/ArkPets.java — 桌宠运行时核心类
- core/src/cn/harryh/arkpets/ArkChar.java — 角色实体类
- core/src/cn/harryh/arkpets/ArkConfig.java — 配置类
- desktop/src/cn/harryh/arkpets/DesktopLauncher.java — 桌面启动器入口
- desktop/src/cn/harryh/arkpets/ArkHomeFX.java — JavaFX 启动器主界面
外部资源：
注：本页为概览级内容，未深入到具体类的逐行实现；
core模块运行时、desktop模块启动器界面、配置解析等主题请参阅对应的兄弟页面。本页引用的源码结构信息（类名、包名、模块划分）来自对仓库*.java文件的包声明扫描，具体类内部逻辑未在本页展开验证。