SAO Utils 2 - NERvGear 开发文档

NERvSDK 1.0
SAO Utils 2 开发从入门到转生
第 2 章 - 打包预置挂件和主题

第 2 章 - 打包预置挂件和主题

讨论、提问及建议等请移步至：

https://nvg.dev/core/sao-utils/issues

https://www.bilibili.com/read/cv28879966

https://github.com/NERvGear/SAO-Utils/issues

前言

本章以制作「Windows XP 主题扩展」为例子，从图标、图片和背景的资源整理开始，一步一步教大家把本地保存的挂件和主题制成「预置挂件」和「预置主题」，并上传到创意工坊或者打包成 NVG 扩展包。

一、文件准备

1. package.json

{
    "name": "com.gpbeta.theme.win-xp",

    "version": "1.0.0",

    "title": {
        "en": "Windows XP Theme Extension",
        "zh": "Windows XP 主题扩展",
        "zh_TW": "Windows XP 主題擴展",
        "ja": "Windows XP テーマ拡張機能"
    },

    "description": {
        "en": "Windows XP widget theme and image resources.",
        "zh": "Windows XP 挂件主题和图片资源。",
        "zh_TW": "Windows XP 掛件主題和圖片資源。",
        "ja": "Windows XP ウィジェットテーマと画像リソース。"
    },

    "dependencies": {
        "com.gpbeta.widget.hud": "*"
    },

    "resources": [
        {
            "location": "/background",
            "catalog": "background/light",
            "title": {
                "en": "Windows XP Backgrounds",
                "zh": "Windows XP 背景",
                "zh_TW": "Windows XP 背景",
                "ja": "Windows XP 背景"
            },
            "entry": "Images/background"
        }, {
            "title": {
                "en": "Windows XP Icons",
                "zh": "Windows XP 图标",
                "zh_TW": "Windows XP 圖標",
                "ja": "Windows XP アイコン"
            },
            "location": "/icon",
            "catalog": "icon/color",
            "entry": "Images/icon"
        }, {
            "title": {
                "en": "Windows XP Images",
                "zh": "Windows XP 图片",
                "zh_TW": "Windows XP 图片",
                "ja": "Windows XP 画像"
            },
            "location": "/image",
            "catalog": "image/widget",
            "entry": "Images/widget"
        }
    ]
}

首先在 SAO Utils 2/Packages 目录内新建文件夹 com.gpbeta.theme.win-xp 并把以上代码保存为 package.json.

可以看到，我们在资源列表中声明了三个资源：

资源 catalog	说明
`"background/light"`	背景资源，指向 Images/background 文件夹
`"icon/color"`	图标资源，指向 Images/icon 文件夹
`"image/widget"`	图片资源，指向 Images/widget 文件夹

Note: 需要注意的是，无论是包名字还是资源 catalog 字段都 只支持 小写字母、减号'-'和下划线'_'。

2. 资源文件

图片资源目录

在开始制作挂件前，我们可以把所有用到的背景、图标和图片放到对应的文件夹内，在配置挂件的时候就可以直接在 SAO Utils 资源选择对话框内找到。

9-patch 背景图

背景资源可以使用一种叫做 9-patch （九宫格图）的特殊 PNG 格式图片。

九宫格图是一种可在安卓开发中使用到的可自定义拉伸的图片标准，其文件格式是标准的 PNG 文件，但必须以 *.9.png 命名。 9-patch 标准简单来说就是在图片的上下左右各留 1px 用于指示拉伸和留白等额外信息。

九宫格图可以通过在线工具 Android Asset Studio 制作。

二、挂件制作

1. 挂件配置

HUD 自定义挂件

你可以使用任意的「基础挂件」用作自己的挂件制作，也可以直接修改别人制作的「预置挂件」作为基底。

背景资源选择

唯一需要注意的是，挂件配置中所有的资源引用必须从第一步中声明的资源列表中选择，任何本地文件，其他人是无法正常显示的。

保存挂件

挂件配置完成后，在【挂件库 - 所有挂件 - 我的挂件】把当前桌面上的挂件保存为「我的挂件」。

2. 主题配置

挂件主题其实就是一组固定位置和大小的挂件配置。

挂件对齐模式

为了适应不同大小和比例的屏幕，制作挂件主题时需要注意挂件的「对齐模式」。

从挂件库拖动到桌面的挂件默认以「绝对定位」模式放置到桌面上，从挂件右键菜单中可以选择如「右上角」「居中」「底部居中」等 9 种屏幕对齐模式。

保存主题

同样，桌面上所有的挂件配置都完成后，在【挂件库 - 主题 - 我的主题】把当前桌面上的挂件保存为「我的主题」。

三、配置转移

1. 迁移我的挂件

接下来把「我的挂件」的配置文件迁移到「Windows XP 主题扩展」的包中。

「我的挂件」配置目录

在 SAO Utils 2/Storages/system/widget-preset 目录下存放了当前玩家保存的「我的挂件」配置文件。

挂件以文件夹划分，如果「我的挂件」中保存了很多挂件的话，会很难找到想要的挂件，推荐以「修改日期」排序方便查找。

「我的挂件」配置文件

「我的挂件」配置目录下每一个文件夹都包含了 3 个文件：

文件名	说明
preset.json	挂件预置信息
preview.png	挂件预览图
settings.xml	挂件配置内容

分别把三个挂件的配置文件都复制到 SAO Utils 2/Packages/com.gpbeta.theme.win-xp/Presets.

为了避免重名，需要把三个挂件相关的文件重命名：

文件名	说明
widget-hdd.*	右上角的磁盘空间挂件
widget-icon.*	左上角的桌面图标挂件
widget-load.*	中央的系统负载挂件

所有配置文件放在一起看起来是这样的：

挂件预置文件

由于我们改变了配置文件的名字，所以三个挂件的 JSON 预置信息文件也要做相应的修改。

{
  "create": "2023-12-28T20:40:52.597Z",
  "source": "nvg://hud.widget.gpbeta.com/widget/adv",
  "title": "系统负载",
  "settings": "widget-load.xml", // 修改
  "edit": "2023-12-29T10:42:19.983Z"
}

预置信息文件的内容非常简单，只需要把 settings 键值改成对应的 XML 配置内容文件名即可。

{
    "location": "/preset/hdd",
    "catalog": "preset/widget",
    "title": {
        "en": "XP HDD Spaces",
        "zh": "XP 磁盘空间",
        "zh_TW": "XP 磁盤空間",
        "ja": "XP HDD 容量"
    },
   "preview": "Presets/widget-hdd.png",
   "entry": "Presets/widget-hdd.json"
}, {
    "location": "/preset/icon",
    "catalog": "preset/widget",
    "title": {
        "en": "XP Desktop Icons",
        "zh": "XP 桌面图标",
        "zh_TW": "XP 桌面圖標",
        "ja": "XP デスクトップアイコン"
    },
   "preview": "Presets/widget-icon.png",
   "entry": "Presets/widget-icon.json"
}, {
    "location": "/preset/load",
    "catalog": "preset/widget",
    "title": {
        "en": "XP System Load",
        "zh": "XP 系统负载",
        "zh_TW": "XP 系統負載",
        "ja": "XP システム情報"
    },
   "preview": "Presets/widget-load.png",
   "entry": "Presets/widget-load.json"
}

最后在 package.json 的 resource 资源列表中加入以上 3 个预置挂件的资源声明。

重启 SAO Utils 后，你就可以在【挂件库 - 所有挂件 - 预置挂件】中找到迁移的挂件了。

2. 迁移我的主题

接下来把「我的主题」的配置文件迁移到「Windows XP 主题扩展」的包中。

主题预置目录

在 SAO Utils 2/Storages/system/widget-theme 目录下存放了当前玩家保存的「我的主题」配置文件，挂件主题同样以文件夹划分。

「我的主题」配置文件

「我的主题」配置目录下每一个文件夹都包含以下文件：

文件名	说明
theme.json	主题预置信息
preview.png	主题预览图
settings-*.xml	每一个挂件配置内容

由于在上一步中，我们已经把挂件的配置内容文件复制过去了。因此，我们只需要把 JSON 和 PNG 两个文件复制到 SAO Utils 2/Packages/com.gpbeta.theme.win-xp/Presets 即可。

同时新的文件名分别改为 theme-widget.json 和 theme-widget.png.

同样，由于我们修改了挂件配置的文件名，因此也需要修改主题的预置信息文件。

{
  "create": "2023-12-29T12:44:32.468Z",
  "widgets": [
    {
      "name": "07e39d9d-b5ed-4011-9c3c-9cc7e1a7b80c", // 整行删除
      "source": "nvg://hud.widget.gpbeta.com/widget/adv",
      "width": 72,
      "height": 390,
      "opacity": 1,
      "location": 1,
      "frame": 2,
      "acceptFocus": true,
      "acceptInput": true,
      "desktop": {
        "x": 16,
        "y": 32,
        "z": -100,
        "anchor": 0, // 注意最后一个逗号要删除
        "screen": "\\\\.\\DISPLAY2", // 整行删除
        "monitor": "49" // 整行删除
      },
      "launcher": {},
      "settings": "widget-icon.xml" // 修改
    },
    {
      "source": "nvg://hud.widget.gpbeta.com/widget/adv",
      "width": 170,
      "height": 240,
      "opacity": 1,
      "location": 1,
      "frame": 2,
      "acceptFocus": true,
      "acceptInput": true,
      "desktop": {
        "x": 32,
        "y": 32,
        "z": -100,
        "anchor": 2
      },
      "launcher": {},
      "settings": "widget-hdd.xml"
    },
    {
      "source": "nvg://hud.widget.gpbeta.com/widget/adv",
      "width": 380,
      "height": 260,
      "opacity": 1,
      "location": 1,
      "frame": 2,
      "acceptFocus": true,
      "acceptInput": true,
      "desktop": {
        "x": 0,
        "y": 0,
        "z": -100,
        "anchor": 4
      },
      "launcher": {},
      "settings": "widget-load.xml"
    }
  ],
  "title": "Windows XP",
  "edit": "2023-12-29T12:45:03.713Z"
}

主题预置信息文件中 widgets 键值储存了所有挂件的预置信息，除了跟之前一样要修改每一个挂件的 settings 键值为对应的配置文件名外，还要对以下键值进行处理：

"name": "<挂件的 UUID>"

每一个放置到桌面的挂件都会生成一个 UUID，这是为了「挂件动作」能找到正确的挂件。
——即便玩家保存到「我的挂件/主题」再恢复到桌面。

如果你的主题没有任何挂件动作，可以把这行删掉以避免挂件 ID 在别人挂件库中 “撞车”。如果你的主题需要使用挂件动作，则推荐使用「分组」标记挂件后在挂件动作中操作。

"screen": "\\\\.\\DISPLAY2",
"monitor": "49"

为了避免挂件每次启动在不同屏幕乱跑，每个挂件都必须跟屏幕绑定，但不是每台电脑的屏幕 ID 是一样的。

删掉这两行可以让主题中所有挂件总是在「主显示器」中摆放。

{
    "location": "/theme/widget",
    "catalog": "theme/widget",
    "title": "Windows XP",
    "preview": "Presets/theme-widget.png",
    "entry": "Presets/theme-widget.json"
}

最后在 package.json 的 resource 资源列表中加入以上挂件主题的资源声明。

重启 SAO Utils 后，你就可以在【挂件库 - 主题 - 预置主题】中找到迁移的主题了。

四、分享扩展

1. 上传至创意工坊

创意工坊导入

在【创意工坊 - 我的工坊 - "+"添加物品 - 导入扩展包】填写物品信息，添加一个封面，选择好扩展包目录，最后点一下「发布」就这么简单。

Note: 需要注意的是，由于 Steam 创意工坊的限制，上传的封面图片不可以超过 1MB。

2. 制作 NVG 扩展包

如果你想以文件形式和别人分享，你还可以制作 NVG 扩展安装包。

NVG 扩展包实际上是 Zip 压缩文件包，可以使用任意压缩工具打包后更改后缀名为 *.nvg 即可。打包好的压缩包目录结构如下：

压缩包的目录结构

打包的时候只需要把扩展的 文件夹内 的文件打包即可，不要包含 扩展包的文件夹。

Note: 注意某些流氓压缩软件会生成套娃格式导致解压失败。

结语

至此，你已完成分享扩展包所需的所有工作，快把你的杰作给小伙伴们爽爽吧！

本文例子「Windows XP 主题扩展」可以在创意工坊订阅，也可以手动下载安装 NVG 扩展包：

https://www.123pan.com/s/BmZKVv-E0On3.html