# wrap-fx-assets

**Repository Path**: simon627/wrap-fx-assets

## Basic Information

- **Project Name**: wrap-fx-assets
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 幻响武器素材库 🔫✨

这里是 **「幻响·腕间音效」**（Xiaomi Vela手表应用）的武器素材仓库！所有武器图片、音效文件都存在这里，通过下载码分发给用户。

## 这仓库是干嘛的？

手表上显示的每一把武器，都需要这些文件：

```
📁 amtls/          ← 阿玛特拉斯（名字）
   ├── amtls-icon.png    ← 480×480 大图标（激活后显示）
   ├── amtls-pre.png     ← 60×60 预览图（菜单里展示）
   └── amtls-audio.mp3   ← 音效（做手势时播放）

📁 lightsaber/      ← 光剑
   ├── lightsaber-icon.png
   ├── lightsaber-pre.png
   └── lightsaber-audio.mp3

📁 weapons-catalog.json   ← 武器目录（告诉应用有哪些武器可用）
```

## 怎么贡献一把新武器？🆕

想把你做的武器加到手表上？按下面几步来就行！

### 第一步：注册 Gitee 账号

1. 打开 [https://gitee.com](https://gitee.com)，点击右上角「注册」
2. 用手机号或邮箱注册，完成登录

### 第二步：准备素材

你需要自己制作 3 个文件。推荐用在线工具（比如搜索"在线图片编辑""在线音频剪辑"等）或下载相关软件。

**图片素材（两张 PNG）：**

| 文件 | 用途 | 尺寸 | 格式 |
|------|------|------|------|
| `{武器id}-icon.png` | 激活后显示的大图 | **480×480 像素** | PNG |
| `{武器id}-pre.png` | 菜单里展示的小图 | **60×60 像素** | PNG |

> 💡 武器 ID 由你自己定，建议用英文或拼音，比如 `wula`（乌拉）、`shouliudan`（手榴弹）。不要用中文或特殊符号。

**音频素材（一个 MP3）：**

| 文件 | 用途 | 格式 |
|------|------|------|
| `{武器id}-audio.mp3` | 做手势时播放的音效 | MP3 |

> 💡 音效建议 3 秒以内，文件越小越好（手表内存有限）。

### 第三步：Fork 仓库并把文件放进来

1. 打开本仓库页面 [https://gitee.com/simon627/wrap-fx-assets](https://gitee.com/simon627/wrap-fx-assets)
2. 点击右上角「Fork」按钮，把仓库复制到你自己的账号下
3. 在你 Fork 后的仓库页面，点击「克隆/下载」，复制 HTTPS 地址
4. 在电脑上找个地方打开终端，运行：

```bash
git clone https://gitee.com/你的用户名/wrap-fx-assets.git
```

5. 在克隆下来的文件夹里，**创建一个新文件夹**，名字就是你的武器 ID（比如 `wula/`）
6. 把准备好的 3 个文件放进这个文件夹：
   - `{武器id}-icon.png`
   - `{武器id}-pre.png`
   - `{武器id}-audio.mp3`
7. **修改 `weapons-catalog.json`**，在文件末尾添加你的武器信息（在最后一个武器后面加逗号 `,` 再粘贴）。格式如下：

```json
{
  "你的武器id": {
    "index": -1,
    "name": "武器名称",
    "description": "武器描述",
    "author": "你的名字",
    "isVip": false,
    "category": "动漫",
    "vibrationDuration": 150,
    "accelerationThreshold": 15.0,
    "deltaThreshold": 10.0,
    "debounceTime": 100,
    "iconUrl": "https://wrap-fx-1327887151.cos.ap-nanjing.myqcloud.com/你的武器id/你的武器id-icon.png",
    "preImgUrl": "https://wrap-fx-1327887151.cos.ap-nanjing.myqcloud.com/你的武器id/你的武器id-pre.png",
    "audioUrls": [
      "https://wrap-fx-1327887151.cos.ap-nanjing.myqcloud.com/你的武器id/你的武器id-audio.mp3"
    ]
  }
}
```

> ⚠️ 注意：`index` 填 `-1`，上传后会自动分配正确的编号。

各字段说明：

| 字段 | 含义 | 建议值 |
|------|------|--------|
| `index` | 武器编号，新武器填 `-1` | `-1` |
| `name` | 武器显示名称 | 中文名 |
| `description` | 武器描述文字 | 一句话 |
| `author` | 作者名 | 你的昵称 |
| `isVip` | 是否 VIP 专属 | `true` 或 `false` |
| `category` | 分类（如：武器、动漫、影视、游戏、搞怪、免费、热梗等） | 自己定 |
| `vibrationDuration` | 震动时长（毫秒） | `50` ~ `150` |
| `accelerationThreshold` | 触发加速度阈值 | `15` ~ `35` |
| `deltaThreshold` | 力度变化阈值 | `6` ~ `25` |
| `debounceTime` | 防抖时间（毫秒），防止误触 | `100` ~ `5000` |
| `iconUrl` / `preImgUrl` | 图片和预览图的网络地址 | 按模板替换 id |
| `audioUrls` | 音效文件地址列表（可多个） | 按模板替换 id |

### 第四步：提交 PR（Pull Request）

1. 在克隆的文件夹里打开终端，依次运行：

```bash
git add .
git commit -m "添加新武器：你的武器名称"
git push origin master
```

2. 回到 Gitee 网页，你的 Fork 仓库页面上会出现一个「Pull Request」按钮，点击它
3. 填写 PR 标题和说明，点「创建」
4. **等待管理员审核**——我会检查文件格式、配置是否正确，没问题就合并到主仓库

### 后续

PR 合并后，管理员会负责把素材上传到云端。**你不需要自己上传。**

## 其他工具 🛠️

### index.html —— 下载码生成器

也在本目录下，双击用浏览器打开。可以：
- **生成下载码**：选择武器组合 → 生成 6 位兑换码
- **解码下载码**：输入 6 位码 → 查看里面包含的武器

编码规则（如果你好奇的话）：
- 6 个字符，用的字母表是 `0123456789ABCDEFGHJKMNPQRSTVWXYZ`（去掉 I L O U 防混淆）
- 前 5 位存数据（武器索引），最后 1 位是校验码
- 一个码可以包含 1~5 把武器

## 文件结构一览 📂

```
D:\wrap-fx-assets\
├── {weaponId}/              ← 每个武器一个文件夹
│   ├── {id}-icon.png        ← 480×480 大图（激活后显示）
│   ├── {id}-pre.png         ← 60×60 小图（菜单展示）
│   └── {id}-audio.mp3       ← 音效
├── weapons-catalog.json     ← 武器目录（核心配置）
├── index.html               ← 下载码生成器
├── pre-img/                 ← 旧版素材（已废弃）
├── images/                  ← 历史遗留图片
└── server/                  ← 后端相关文件（不常用）
```

## 常见问题 ❓

**Q: 我怎么确认文件格式不对？**
A: icon 图片必须是 **480×480 像素**的 PNG，pre 图片必须是 **60×60 像素**的 PNG。音效必须是 MP3。如果尺寸不对，手表上可能会显示异常。

**Q: 我的 PR 被拒绝了，怎么办？**
A: 看看管理员在 PR 里的评论，按要求修改后 `git add` 再 `git push` 就行了，PR 会自动更新。

**Q: 我想删一把武器？**
A: 把对应的文件夹删掉，从 `weapons-catalog.json` 里删除对应的条目，然后提交 PR。

## 注意事项 ⚠️

- **不要修改别人的武器文件**，除非确实需要
- **不要删除不认识的文件夹**
- **提交前确认 weapons-catalog.json 是合法的 JSON**（可以在网上搜"JSON 验证"在线工具检查）

---

有问题直接问！🎉