Doc Update

isHarryh · Dec 31, 2023 · 5ccaaf3 · 5ccaaf3
1 parent 727a34e
commit 5ccaaf3
Show file tree

Hide file tree

Showing 5 changed files with 144 additions and 38 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,11 +3,32 @@
 ***目前最新可用版本：***
 [<img alt="GitHub latest release" src="https://img.shields.io/github/v/release/isHarryh/Ark-Pets?display_name=tag&label=Version&sort=semver&include_prereleases">](https://github.com/isHarryh/Ark-Pets/releases)
 
+## v2.4
+| **新增**      |                                                     |
+|:------------|:----------------------------------------------------|
+| [`4754554`] | 新增了在下载对话框中显示下载速率的功能。                                |
+| [`1eb6c08`] | 新增了**模型库下载源** ghproxy.harryh.cn，取代了原来的 ghproxy.com。 |
+| [`a5c7b9a`] | 新增了可以**导入模型仓库的压缩包**以加载模型的功能。<br>新增了一些启动器页面跳转逻辑。     |
+| [`727a34e`] | 新增了启动器的网络代理设置项。                                     |
+
+| **修复**      |                              |
+|:------------|:-----------------------------|
+| [`cb06cba`] | 修复了启动器内弹出的对话框在关闭时未播放关闭动画的问题。 |
+
+| **优化**                     |                                                |
+|:---------------------------|:-----------------------------------------------|
+| [`cb06cba`]                | 重构了**启动器前台任务**的代码逻辑。                           |
+| [`1eb6c08`]                | 优化了控制台日志，输出流与错误流相分离。                           |
+| [`#52`]<br>[`#55`]         | 优化了**自动化构建**，在 GitHub Actions 新增了 `build` 工作流。 |
+| [`3b8f5fc`]<br>[`abc4743`] | 修订并公布了代码检查规则。                                  |
+| [`f6139c3`]                | 重构了**模型资源**的代码逻辑。                              |
+| [`#47`]<br>[`7db99c3`]     | 优化了 Windows 安装程序的默认安装目录和在控制面板卸载页面中的表现。         |
+
 ## v2.3
-| **新增**      |                                          |
-|:------------|:-----------------------------------------|
-| [`a31afcf`] | 新增了右键桌宠本体即可弹出菜单的功能。                      |
-| [`17d3fde`] | 新增了可以在菜单中切换桌宠形态的功能，现在可以切换拥有多个形态的敌方领袖的形态。 |
+| **新增**      |                                              |
+|:------------|:---------------------------------------------|
+| [`a31afcf`] | 新增了**右键桌宠本体即可弹出菜单**的功能。                      |
+| [`17d3fde`] | 新增了可以在菜单中**切换桌宠形态**的功能，现在可以切换拥有多个形态的敌方领袖的形态。 |
 
 | **修复**                 |                                                  |
 |:-----------------------|:-------------------------------------------------|
@@ -18,8 +39,8 @@
 | **优化**      |                                          |
 |:------------|:-----------------------------------------|
 | [`0fb103c`] | 优化了 Windows 安装程序的语言本地化（修订了简体中文，新增了繁体中文）。 |
-| [`a31afcf`] | 优化了托盘菜单的外观表现。                            |
-| [`e046e1c`] | 优化了动画队列的代码逻辑。                            |
+| [`a31afcf`] | 优化了**托盘菜单**的外观表现。                        |
+| [`e046e1c`] | 优化了**动画队列**的代码逻辑。                        |
 
 | **补丁**                  |                    |
 |:------------------------|:-------------------|
@@ -213,7 +234,10 @@
 [`#12`]: https://github.com/isHarryh/Ark-Pets/issues/12
 [`#34`]: https://github.com/isHarryh/Ark-Pets/issues/34
 [`#39`]: https://github.com/isHarryh/Ark-Pets/issues/39
+[`#47`]: https://github.com/isHarryh/Ark-Pets/issues/47
 [`#48`]: https://github.com/isHarryh/Ark-Pets/issues/48
+[`#52`]: https://github.com/isHarryh/Ark-Pets/issues/52
+[`#55`]: https://github.com/isHarryh/Ark-Pets/issues/55
 [`2bc0079`]: https://github.com/isHarryh/Ark-Pets/commit/2bc0079b922684b1d4850f9211225dcf803e555c
 [`48ef339`]: https://github.com/isHarryh/Ark-Pets/commit/48ef339dd78711e208ded8c5148569d8b89690b1
 [`95e6a1a`]: https://github.com/isHarryh/Ark-Pets/commit/95e6a1ace8d047ac51314e7d5572ce4169fa9f84
@@ -267,3 +291,12 @@
 [`e046e1c`]: https://github.com/isHarryh/Ark-Pets/commit/e046e1c67ccbd61cde7e50927eccf9c20c7ee736
 [`b72421a`]: https://github.com/isHarryh/Ark-Pets/commit/b72421a90b9263c6f25fe76053f139ffa445a981
 [`7a161d3`]: https://github.com/isHarryh/Ark-Pets/commit/7a161d304f4256d0dfa5f027fad1479ac0d06391
+[`cb06cba`]: https://github.com/isHarryh/Ark-Pets/commit/cb06cba4e14838da89e4ea5c10cd29c402719985
+[`4754554`]: https://github.com/isHarryh/Ark-Pets/commit/4754554ae9356f53f34313b8cfc1abc4fb57fd9b
+[`1eb6c08`]: https://github.com/isHarryh/Ark-Pets/commit/1eb6c087b2b7587bfb9de38daabb9060dd0bfba7
+[`3b8f5fc`]: https://github.com/isHarryh/Ark-Pets/commit/3b8f5fc2db55cd0916a6a9207b733f015951f746
+[`f6139c3`]: https://github.com/isHarryh/Ark-Pets/commit/f6139c3890f1a23fc6abf71d62e8def0e17bb72e
+[`abc4743`]: https://github.com/isHarryh/Ark-Pets/commit/abc4743ae4e4b2a854e405008de2bb7269ac6b17
+[`7db99c3`]: https://github.com/isHarryh/Ark-Pets/commit/7db99c32f44d86ff23b9857fec21e5e024f8a9b8
+[`a5c7b9a`]: https://github.com/isHarryh/Ark-Pets/commit/a5c7b9a99f4fd79d4f92497a7a855c71ba112dcb
+[`727a34e`]: https://github.com/isHarryh/Ark-Pets/commit/727a34eed5d1a41ee3e6f153726f2bcf92a28958
diff --git a/README.md b/README.md
@@ -1,12 +1,13 @@
 <!-- 欢迎阅读 Ark-Pets 说明文档 -->
 <!-- 仓库：https://github.com/isHarryh/Ark-Pets -->
 
+<!--suppress HtmlDeprecatedAttribute -->
 <div align="center" style="text-align:center">
    <h1> Ark-Pets </h1>
    <img alt="ArkPets icon" width="64" src="https://raw.githubusercontent.com/isHarryh/Ark-Pets/v2.x/assets/icons/icon.png"/>
    <p>
       Arknights Desktop Pets | 明日方舟桌宠 <br>
-      <code><b> v2.3 </b></code>
+      <code><b> v2.4 </b></code>
    </p>
    <p>
       <img alt="GitHub Top Language" src="https://img.shields.io/github/languages/top/isHarryh/Ark-Pets?label=Java">
@@ -59,10 +60,13 @@
 
 ### 下一步计划
 
-以下内容可能在接下来的数个版本内得到实现：
+当前版本 **v2.4** 将成为 ArkPets v2.x 系列的**最后一个**子版本。
+
+以下内容将在 ArkPets v3.x 系列实现：
 
 - 支持高级筛选和收藏夹功能
 - 支持将动态立绘作为桌宠启动
+- 全面更新依赖库的版本
 
 以下内容仍需进一步的探索：
 
@@ -85,18 +89,17 @@
 1. 请[**前往此页面**](https://github.com/isHarryh/Ark-Pets/releases)下载最新的 **ArkPets-Setup.exe** 安装包。
 2. 下载完成后，请运行所下载的安装包以进行软件的安装。
 3. 安装完成后，请通过桌面快捷方式等途径，打开 ArkPets 启动器。
-4. 打开启动器后，首次使用需要 **下载模型文件** 。请进入启动器“选项”页面，在“模型下载”处点击“全部下载”。（下载过程可能持续1~
-   2分钟，下载总大小约为140MB）
+4. 打开启动器后，首次使用需要 **下载模型文件** 。请进入启动器“选项”页面，在“模型下载”处点击“全部下载”。
 5. 最后，进入启动器“模型”页面即可检索并选中想要作为桌宠启动的角色，然后点击左下角“启动”按钮即可。
 
 > 提示：
 > - 本程序当前只支持在`Windows`系统上运行。
-> - 如需更新软件，无需手动卸载后再安装，直接运行安装包即可。
+> - 如需更新软件到 v2.x 的更高版本，无需预先手动卸载，直接运行安装包即可。
 > - 如需关闭已启动的桌宠，请右键点击系统托盘中的 ArkPets 图标，然后选择“退出”。
 
 ### 额外说明
 
-- *检查模型库更新* ：我们的模型库不定时更新，如果您想体验新实装进游戏的模型，可以进入启动器“选项”页面，在“模型下载”处点击“检查更新”。如果提示有更新，点击“全部下载”就能完成模型库更新。
+- *检查模型库更新* ：我们的模型库不定期更新，如果您想体验新实装进游戏的模型，可以进入启动器“选项”页面，在“模型下载”处点击“检查更新”。如果提示有更新，点击“全部下载”就能完成模型库更新。
 - *开机自启动* ：进入启动器“选项”页面可以设置开机自启动，设置后下一次电脑开机会自动生成最后一次启动的桌宠。
 - *透明模式* ：为防止用户在游戏、观看视频等情景下误触到桌宠，特增加了此模式。右键托盘后打开“透明模式”，即可屏蔽桌宠和鼠标的一切交互（点击、拖动操作都将穿透到下层窗口），并且桌宠的不透明度会降低。
 - *下边界距离* ：桌宠在部分用户的电脑上无法正常检测任务栏位置（桌宠会沉入任务栏），此时您可以手动设置任务栏高度。进入启动器“选项”页面可以调整下边界距离，通常会将其设置为15的正整数倍。

diff --git a/core/src/cn/harryh/arkpets/assets/AssetItemGroup.java b/core/src/cn/harryh/arkpets/assets/AssetItemGroup.java
@@ -13,6 +13,7 @@
  * <hr>
  * The structure of the root directory may be like what is shown below.
  * Each {@code SubDir} represents an {@code AssetItem}.
+ *
  * <blockquote><pre>
  * +-RootDir
  * |-+-SubDir1 (whose name is the model name of xxx)
@@ -23,6 +24,7 @@
  * |---SubDir3
  * |---...</pre>
  * </blockquote>
+ *
  * @since ArkPets 2.4
  */
 public class AssetItemGroup implements Collection<AssetItem> {
@@ -36,6 +38,10 @@ public AssetItemGroup() {
         this(new ArrayList<>());
     }
 
+    /** Searches the Asset Items whose {@code name} and {@code appellation} match the given keywords.
+     * @param keyWords The given keywords. Each keyword should be separated by a blank.
+     * @return An Asset Item Group. Returns {@code this} if the parameter {@code keyWords} is {@code null} or empty.
+     */
     public AssetItemGroup searchByKeyWords(String keyWords) {
         if (keyWords == null || keyWords.isEmpty())
             return this;
@@ -59,6 +65,10 @@ public AssetItemGroup searchByKeyWords(String keyWords) {
         return result;
     }
 
+    /** Searches the Asset Item whose relative path provided by {@code getLocation} matches the given path string.
+     * @param relPath The given path string.
+     * @return The first matched Asset Item. Returns {@code null} if no one matched.
+     */
     public AssetItem searchByRelPath(String relPath) {
         if (relPath == null || relPath.isEmpty())
             return null;
@@ -68,17 +78,33 @@ public AssetItem searchByRelPath(String relPath) {
         return null;
     }
 
+    /** Collects the values of a specified property of the Asset Items.
+     * @param property A property extractor.
+     * @return A Set that contains all the possible values of the property.
+     * @param <T> The type of the property value.
+     */
     public <T> Set<T> extract(PropertyExtractor<T> property) {
         HashSet<T> result = new HashSet<>();
         for (AssetItem item : this)
             result.addAll(property.apply(item));
         return result;
     }
 
+    /** Returns a new Asset Item Group consisting of the Asset Items that match the given predicate.
+     * @param predicate A predicate to apply to each Asset Item to determine if it should be included.
+     * @return An Asset Item Group.
+     */
     public AssetItemGroup filter(Predicate<AssetItem> predicate) {
         return new AssetItemGroup(assetItemList.stream().filter(predicate).toList());
     }
 
+    /** Returns a new Asset Item Group consisting of the Asset Items whose property satisfied the requirements.
+     * @param property A property extractor.
+     * @param filterValues The property values to be matched.
+     * @param mode The {@link AssetItemGroup.FilterMode}.
+     * @return An Asset Item Group.
+     * @param <T> The type of the property value.
+     */
     public <T> AssetItemGroup filter(PropertyExtractor<T> property, Set<T> filterValues, int mode) {
         final boolean TRUE = (mode & FilterMode.MATCH_REVERSE) == 0;
         return filter(assetItem -> {
@@ -95,10 +121,18 @@ public <T> AssetItemGroup filter(PropertyExtractor<T> property, Set<T> filterVal
         });
     }
 
+    /** Returns a new Asset Item Group consisting of the Asset Items whose property satisfied the requirements.
+     * @param property A property extractor.
+     * @param filterValues The property values to be matched.
+     * @return An Asset Item Group.
+     * @param <T> The type of the property value.
+     */
     public <T> AssetItemGroup filter(PropertyExtractor<T> property, Set<T> filterValues) {
         return filter(property, filterValues, 0);
     }
 
+    /** Sorts the Asset Items by their {@code assetDir} in natural order.
+     */
     public void sort() {
         assetItemList.sort(Comparator.comparing(asset -> asset.assetDir, Comparator.naturalOrder()));
     }

diff --git a/docs/CustomModel.md b/docs/CustomModel.md
@@ -2,31 +2,62 @@ ArkPets附加说明文档
 # 自定义模型
 
 ArkPets 添加自定义 Spine 模型的方法。
+> 注意：  
+> 本文档适用于 ArkPets v2.x，不同版本的 ArkPets 的模型管理逻辑可能有较大差异。
 
 ### 前提
-- **熟悉 JSON 数据格式。**
-- 所要添加的模型的 **Spine版本必须是 3.8** ，这也是截至本文档撰写时《明日方舟》所使用的版本。不同版本的Spine之间的兼容性较差，您可以使用文本编辑器强制查看小人.skel文件的头部信息，以确定其Spine版本。
-- 所要添加的模型必须是《明日方舟》中的游戏模型，如果不是，那么该模型包含的动画名称必须与《明日方舟》的动画名称命名方式一致。
+1. **熟悉 JSON 数据格式。**
+2. 所要添加的模型的 **Spine 版本必须是 3.8**，这也是截至本文档撰写时《明日方舟》所使用的 Spine 的版本。不同版本的 Spine 之间的兼容性较差，您可以使用文本编辑器强制查看小人骨骼（.skel）文件的头部信息，以确定其 Spine 版本。
+3. 所要添加的模型必须是《明日方舟》中的角色模型，如果不是，那么该模型包含的动画名称必须与《明日方舟》中的动画名称命名方式一致。关于命名方式，参见本项目 Java 源码 `cn.harryh.arkpets.animations.AnimClip` 中的 `AnimType` 枚举）。
 
 ### 步骤
-1. 安装 ArkPets 并确保已在 [选项] 中下载了模型。
-2. 将所要添加的模型的资源文件（包括 .atlas .png .skel）放入文件夹 _A_ 中，然后将文件夹 _A_ 放到程序目录中的 `models` 资源文件夹中。
-    > 也可以放到其他资源文件夹，但是需要进行额外的操作。假设把文件夹 _A_ 放到了程序目录中的文件夹 _B_ 中，且模型的 `type` 值是 _C_ ，那么程序目录中的 `models_data.json` 的 `storageDirectory` 字段中需要添加键值对 `"C" : "B"`。
-3. 在程序目录中的 `models_data.json`，找到 `data` 字段。仿照其他模型对象的格式，加入你所要添加的新模型的信息，示例如下：
+下面将演示如何添加名称为 `MyModel` 的干员类型（Operator）的模型到 ArkPets 中：
+
+1. 在程序工作目录（下简称“根目录”）中创建一个数据集文件 `models_data.json` 和一个总模型文件夹 `models`。  
+   数据集文件的格式如下（标注星号 `*` 者为必需条目）：
    ```json
-   "285_medic2": { // 键需要设置为模型文件夹A的名称（重要）
-       "assetId": "build_char_285_medic2", // 模型资源文件的纯文件名称（去掉扩展名）
-       "type": "Operator",
-       "style": null,
-       "name": "Lancet-2", // 模型在启动器中显示的名称
+   {
+       "storageDirectory": {
+           // * 每种模型类型所对应的总模型文件夹名称
+           "Operator": "models"
+        },
+       "sortTags": {
+            // 每个模型标签所对应的本地化描述
+            "Operator": "干员",
+            "Skinned": "时装"
+        },
+        "gameDataVersionDescription": "xxxxx", // 游戏数据版本描述
+        "gameDataServerRegion": "zh_CN", // 游戏数据服务器地区描述
+        "data": {
+            // * 每个模型的信息
+            // ...
+        },
+        "arkPetsCompatibility": [2, 0, 0] // ArkPets 兼容性版本标识
+   }
+   ```
+   > 提示：
+   > 1. 也可以通过启动器 “选项” 页的模型下载或导入功能来导入 ArkModels 仓库的数据集文件和总模型文件夹。
+   > 2. 总资源文件夹的名称可以是其他名称，但是需要为数据集文件中的 `storageDirectory` 字段中添加一个键值对 `"角色类型" : "总资源文件夹名"`。
+2. 将所要添加的模型的资源文件（包括 .atlas .png .skel 文件）放入同一个文件夹（下称“单模型文件夹”）中，然后将单模型文件夹放入总资源文件夹中。
+3. 在数据集文件中的 `data` 字段中，仿照其他模型对象的格式，加入你所要添加的新模型的信息，示例如下（标注星号 `*` 者为必需条目）：
+   ```json lines
+   "my_model": { // * 单模型文件夹的名称
+       "assetId": "build_my_model", // * 模型资源文件的纯文件名称（去掉扩展名）
+       "type": "Operator", // * 模型类型
+       "style": "BuildingDefault", // 模型子类型
+       "name": "My Model", // * 角色名称
        "sortTags": [
+            // 模型标签
            "Operator"
        ],
-       "appellation": null,
-       "skinGroupId": null,
-       "skinGroupName": null,
-       "checksum": null
+       "appellation": "My Model", // 角色代号
+       "skinGroupId": "ILLUST", // 时装系列编号
+       "skinGroupName": "默认服装", // 时装系列名称
+       "checksum": { // 文件 MD5 校验和
+            ".atlas": "xxxxx",
+            ".png": "xxxxx",
+            ".skel": "xxxxx"
+       }
    }
    ```
-   上方示例中，大部分字段都可以设为 `null`，它们的具体功能在此不进行介绍，可自行探索。
-4. 重新打开启动器即可找到已添加的自定义模型。若未在启动器中找到自定义模型，请检查你的操作和相关拼写。
+4. 打开 ArkPets 启动器，进行模型 “重载” 后，即可载入自定义模型。若未在启动器中找到自定义模型，请检查相关操作和拼写。