AssetDirector

AssetDirector 从 Mojang 官方接口下载 1.13+ 的资源（语言文件、声音、纹理）到本地，让 1.7.10 的 mod 也能用新内容，且不违反 EULA。宿主 mod 只需声明"我需要哪些资源"，不需要管下载逻辑。

基本信息

属性	值
类型	共享模块 / 资源下载
入口类	`AssetDirectorAPI`（`makamys.mclib.ext.assetdirector`）
调用时机	任意时候，pre-init 之前
运行端	仅客户端（`FMLLaunchHandler.side() == Side.CLIENT` 才生效）
配置文件	无。只读系统属性，见下文

AssetDirectorAPI

成员	签名	说明
注册资源	`public static void register(ADConfig config)`	把配置对象序列化成 JSON 字符串存进共享 map，键为 `Loader.instance().activeModContainer().getModId()`。转成 JSON 是为了消除类身份——不同 mod shade 进去的 `ADConfig` 是不同类，无法直接放进同一个 map
静态块	—	客户端下立刻通过 TaskQueue 排一个名为 `"AssetDirectorPreinit"` 的 pre-init 任务
内部存储	`static Map<String, String> jsons`	走共享状态，键 `AssetDirector` / `jsons`

同一个 modid 重复 register 会覆盖旧配置。

ADConfig

包路径 makamys.mclib.ext.assetdirector。用 Lombok @Data / @AllArgsConstructor 简化样板。

方法	签名	作用
添加单个资源对象	`addObject(String version, String path)`	如 `"minecraft/lang/ms_my.json"`、`"minecraft/sounds/item/bucket/fill_axolotl1.ogg"`
添加声音事件（两参）	`addSoundEvent(String version, String name)`	category 传 null
添加声音事件（三参）	`addSoundEvent(String version, String name, String category)`	自动把 `sounds.json` 里该事件引用的所有 `.ogg` 加入下载队列
添加客户端 jar	`addJar(String version)`	下载并挂载整包 `minecraft.jar`，用于 1.13 之后新增、1.7.10 assets 里没有的文件

内部结构：

类型	字段
`ADConfig`	`Map<String, VersionAssets> assets`，键为版本号
`ADConfig.VersionAssets`	`Set<String> objects`、`Set<SoundEvent> soundEvents`、`boolean jar`
`ADConfig.VersionAssets.SoundEvent`	`public String name`、`public String category`

使用示例（源码内 `ext/assetdirector/test/ADTest.java`）

仓库里带了一个可运行的示例 mod：声明 1.17 的马来语语言文件、music_disc.pigstep 声音事件（故意请求两次 record 与 music 以测试冲突处理）、1.17 的客户端 jar、1.19.3 的语言文件；随后在 pre-init 客户端侧把 Blocks.gold_block 的贴图名改成 minecraft_1.17:gold_block，并从资源管理器里读出 1.17 与 1.19.3 的语言 JSON。

声音事件的 category 覆盖规则

AssetDirector.getObjectsAndSetCategories 的行为：

在目标版本的 sounds.json 里查事件名；查不到则 LOGGER.warn("Mod <id> requested non-existent sound event <name>")。
遍历该事件 sounds 数组，元素是字符串就取其值，是对象就取 name 字段，拼成 "minecraft/sounds/" + soundPath + ".ogg" 加入下载队列。
若事件已有 category 且与请求的不同，只 LOGGER.warn 提示"忽略 mod 的 category 请求"；若事件没有 category，才写入请求的 category。
把事件名记入临时键 ":tmp:requested"（常量 AssetDirector.SOUNDS_JSON_REQUESTED），渲染给游戏前会被剥掉。

离线处理

AssetDirector.preInit 逐 mod 解析，出错时若异常是 UnknownHostException 或 SocketTimeoutException，会 LOGGER.error("Aborting further asset downloads since we seem to be offline.") 并跳过后续所有 mod 的下载。

系统属性（无配置文件）

属性	默认值	作用
`assetDirector.manifestEndpoint`	`https://launchermeta.mojang.com/mc/game/version_manifest.json`	版本清单接口
`assetDirector.resourcesEndpoint`	`https://resources.download.minecraft.net`	资源对象下载接口
`assetDirector.downloadTimeout`	`10000`（毫秒）	下载连接/读取超时
`assetDirector.downloadAttempts`	`3`	单个资源哈希校验失败后的重试次数
`assetDirector.dumpSoundsJson`	`false`	开启后把整形后的 `sounds.json` 导出到 `<实例>/asset_director/out/sounds-<version>.json`
`minecraft.sharedDataDir`	回退到环境变量 `MINECRAFT_SHARED_DATA_DIR`	指定后 AssetDirector 数据目录为 `<sharedDataDir>/asset_director`

数据目录选择逻辑见 AssetDirector.getAssetDirectorDir：优先共享数据目录；否则用 assets 目录下的 asset_director；检测到旧版官方启动器（launcher_profiles.json 中 launcherVersion.name 版本号 <= 1.6.93）时，因为旧启动器会清理 assets 目录的多余文件，改用 assets/../asset_director。