ArenaPro 客户端资源管理

通过这种方式，你可以彻底脱离“地图内的文件管理系统”，将资源索引与引用完全交给本地工程维护：更易版本化、更易协作、更易回溯。生成的本地枚举索引可直接分享给任何人、放入任意仓库，在不同地图中即拷即用、开箱即用，引用资源像写常量一样可靠。

重要提示：本地维护 vs 引擎存储

• 索引与引用均为“本地维护资源”，独立于地图内的文件管理系统，可直接纳入 Git 等版本库，方便协作与回溯。
• 不依赖地图资源库：无需把索引写入地图或依赖地图权限，代码侧即可“有名可查、即引即用”。
• 真正跨地图复用：同一套索引可在不同项目/地图中复用，分享给团队成员即可立即使用（开箱即用）。

开始批量上传

1. 打开 VS Code，按下 Ctrl + Shift + P 打开命令面板。
2. 搜索并选择命令：
   • 批量上传图片：命令 “批量上传图片（本地维护）”
   • 批量上传音频：命令 “批量上传音频（本地维护）”
3. 在系统文件选择器中：
   • 开启多选，选择需上传的文件。
   • 图片支持扩展名：jfif, pjpeg, jpg, jpeg, pjp, png
   • 音频支持扩展名：mp3, wav, ogg, webm
4. 点击“上传”。插件将逐个上传并在本地枚举文件中追加索引项。
5. 完成后，你会看到信息提示：
   • 有多少条因“标识符重复”或“值重复”而跳过

生成结果与文件位置

• 输出根目录：client/UiIndex/assets/
• 文件与导出：
  • 图片：GamePictureUrl.ts 导出 export enum GamePictureUrl { ... }
  • 音频：GameAudioUrl.ts 导出 export enum GameAudioUrl { ... }

文件头包含说明与生成时间，枚举条目按键名排序，统一两空格缩进，并以逗号结尾。

键名生成规则（非常重要）

• 取文件“基本名”（去掉扩展名），规则转换：
  • 非字母数字的分隔符统一打散并“单词化”，每个单词首字母大写，最后拼接
  • 首字符若非法，前置下划线 _
  • 示例：
    • main-bg.png → MainBg
    • 1_logo.png → _1Logo
    • ui icon large.png → UiIconLarge

经验法则：尽量使用清晰的英文单词、数字、- 或 _。避免混杂空格和特殊符号，减少意外键名。

去重与提示规则

追加时会进行两类去重判断：

• 标识符重复（Key 重复）：如果已存在同名键，跳过。
• 值重复（Value 重复）：如果已存在相同的 URL/哈希值，跳过。

完成后会弹出信息框，汇总：

• 跳过总数（包含“标识符重复”数量与示例、“值重复”数量与示例）

若一次未新增任何条目但存在跳过，也会弹出“跳过原因”的警告提示。

在代码中引用资源

生成后的文件导出为标准枚举，使用方式如下：

// 示例：图片
import { GamePictureUrl } from "@client/UiIndex/assets/GamePictureUrl";

const heroUrl = GamePictureUrl.HeroMain; // 假设生成了该键

// 示例：音频
import { GameAudioUrl } from "@client/UiIndex/assets/GameAudioUrl";

const clickSound = GameAudioUrl.UiClick; // 假设生成了该键

小技巧：为枚举项添加注释，获得悬浮提示与更友好的自动补全

你可以在每个枚举项上方添加 JSDoc 风格的块注释 /** ... */，为团队提供更清晰的用途说明、尺寸/时长、注意事项等信息。这些注释会在 IDE 悬浮时展示，也会作为智能提示的一部分。

// client/UiIndex/assets/GamePictureUrl.ts
export enum GamePictureUrl {
  /** 主角立绘（首页 Banner 使用），1920x1080，PNG，≤200KB */
  HeroMain = "https://.../hero-main.png",

  /** UI 基础图标（通用），64x64，Sprite 集合 */
  UiIconBase = "https://.../ui-icon-base.png",
}

// client/UiIndex/assets/GameAudioUrl.ts
export enum GameAudioUrl {
  /** UI 点击音效，时长 ~120ms，音量建议 -6dB */
  UiClick = "https://.../ui-click.mp3",

  /** 成就解锁音效，时长 ~900ms，含渐强尾音 */
  AchievementUnlock = "https://.../achievement-unlock.mp3",
}

注意：枚举文件会被“追加写入”。新增条目不会覆盖你已有的条目与注释；

小贴士：可在团队约定一个注释模板，例如“用途/尺寸或时长/格式/注意项”，保持一致性： /** 用途（位置）｜尺寸/时长｜格式｜注意项 */

辅助工具：在编辑器中直接预览图片链接

配合 VS Code 扩展 Gutter Preview，可以在编辑代码时直接于编辑器行号边的“gutter”区域预览图片，提升资源校对效率。

• 安装：在 VS Code 扩展市场搜索 “Gutter Preview” 并安装。
• 使用：当光标所在行包含图片 URL 或本地相对路径时，gutter 会出现该图片的缩略图；将鼠标悬浮其上可放大预览。
• 适用场景：在 GamePictureUrl、UI 配置、样式或 JSON 配置中快速核对图片是否为预期资源。
• 兼容性：支持常见图片格式及 http/https、相对/绝对路径。（具体以扩展说明为准）
• 性能建议：对超大图或网络较慢时，可临时禁用预览或限制预览大小以避免编辑器卡顿。

常见问题（FAQ）

• Q: 为什么我上传后，没有新增条目？

  • A: 可能是“标识符重复”或“值重复”。插件会提示跳过原因。可以更改文件名（影响键名）或确认是否重复上传了相同的资源 URL。

• Q: 键名不符合预期？

  • A: 键名由文件“基本名”转成 PascalCase。请按你的命名需要调整文件名（尽量使用清晰的英文/数字/下划线/连接符），避免过多特殊字符。

• Q: 为什么说“本地维护”？会丢吗？

  • A: 该索引不存储于 BOX3 引擎中，位于本地输出目录下，建议纳入你的项目并进行版本管理，避免丢失。

最佳实践建议

• 使用规范化文件名，直观地产生语义化枚举键。
• 对于会频繁复用的资源（例如 UI 图标、基础音效），建议统一命名前缀，便于在工程内检索。
• 批量上传后，提交到版本库（例如 Git），并为关键版本打标签，避免回退困难。
• 定期清理未使用的枚举项，保持索引清爽与可维护。