From 4f8b166f8f866280f13b2daad72ad9d5477cef0f Mon Sep 17 00:00:00 2001 From: Xin Luo <104831916+3453890470@users.noreply.github.com> Date: Fri, 20 Feb 2026 04:16:06 +0800 Subject: [PATCH 1/2] docs(readme): complete ExtraLoader usage and compatibility guide --- README.md | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 192 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 11e896c..6a4c293 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,195 @@ # Extra Loader -Load extra resource packs and data packs for you. +一个 Forge 模组，通过约定优于配置的方式加载额外的资源包和数据包。 +## 功能特点 + +- **自动检测包类型**：根据包内是否包含 `assets/` 或 `data/` 目录自动识别资源包或数据包 +- **三种加载模式**： + - `required/` - 必须启用的包（红色标识，无法禁用） + - `optional/` - 可选包（青色标识，默认禁用） + - `default/` - 默认启用的包（绿色标识，可手动禁用） +- **支持多种包格式**：支持路径包（目录）和文件包（.zip/.jar） +- **系统级配置**：支持全局配置选项，管理包的启用/禁用 + +## 兼容性 + +- **Minecraft 版本**：支持所有 Minecraft 1.20+ 版本 +- **Forge 版本**：需要 Forge 1.20+ / NeoForge 1.20+ +- **Java 版本**：Java 17+ + +## 安装步骤 + +### 客户端安装 + +1. 下载 **ExtraLoader** 模组文件（JAR 格式） +2. 将模组文件放入 Minecraft 的 `mods/` 文件夹 +3. 启动游戏 + +### 服务端安装 + +1. 下载 **ExtraLoader** 模组文件（JAR 格式） +2. 将模组文件放入服务器上的 `mods/` 文件夹 +3. 启动服务器 + +> **注意**：ExtraLoader 仅在 Forge 1.20+ 环境中运行，不支持其他模组加载器。 + +## 目录结构 + +### 全局包目录 + +模组会在游戏目录下创建 `extraloader/` 文件夹： + +``` +<游戏目录>/ +└── extraloader/ + ├── required/ # 必须启用的包 + ├── optional/ # 可选包 + └── default/ # 默认启用的包 +``` + +### 系统全局包目录 + +模组还会在用户目录下创建系统级包目录： + +``` +<用户目录>/ +└── .extraloader/ + └── / # 自动根据 Minecraft 版本创建子目录 + ├── required/ + ├── optional/ + └── default/ +``` + +### 加载模式说明 + +| 模式文件夹 | 包的状态 | 颜色标识 | 是否可禁用 | +| ----------- | -------------- | -------- | ---------- | +| `required/` | 必须启用 | 红色 | 否 | +| `optional/` | 可选，默认禁用 | 青色 | 是 | +| `default/` | 默认启用 | 绿色 | 是 | + +### 包类型识别 + +ExtraLoader 会自动检测包的类型： + +- **资源包**：包含 `assets/` 目录的包 +- **数据包**：包含 `data/` 目录的包 + +> **重要**：不需要在文件夹名称中指定 `resourcepacks/` 或 `datapacks/`，模组会根据包内容自动识别。 + +## 常用配置项 + +ExtraLoader 的配置文件位于 Minecraft 配置目录，包含以下配置项： + +### Common 配置 + +| 配置项 | 类型 | 默认值 | 说明 | +| ------------------------- | ------- | ------ | ---------------------- | +| `enableSystemGlobalPacks` | Boolean | `true` | 是否启用系统全局包目录 | + +### Client 配置 + +| 配置项 | 类型 | 默认值 | 说明 | +| ----------------------- | ---- | ------ | -------------------- | +| `disabledResourcePacks` | List | `[]` | 禁用的资源包 ID 列表 | + +### 配置文件示例 + +`config/extraloader-common.toml`: + +```toml +enableSystemGlobalPacks = true +``` + +`config/extraloader-client.toml`: + +```toml +disabledResourcePacks = [] +``` + +## 使用示例 + +### 示例 1：启用主题包 + +1. 在 `extraloader/default/` 目录下放置主题包（.zip 或目录） +2. 包内容应包含 `assets/minecraft/textures/gui/title.png` +3. 启动游戏后，主题包会自动启用（绿色） + +### 示例 2：使用强制资源包 + +1. 在 `extraloader/required/` 目录下放置强制包 +2. 包内容应包含 `assets/minecraft/textures/` 目录 +3. 启动游戏后，强制包会自动启用且无法禁用（红色） + +### 示例 3：禁用某个资源包 + +1. 打开 `config/extraloader-client.toml` +2. 在 `disabledResourcePacks` 列表中添加包的 ID： + +```toml +disabledResourcePacks = [ + "extraloader/default/example-theme.zip" +] +``` + +## 常见问题 + +### 1. 模组加载后看不到我的包 + +**可能原因**： + +- 包放在了错误的文件夹（如 `resourcepacks/` 而不是 `extraloader/default/`） +- 包缺少 `pack.mcmeta` 文件 +- 包内没有 `assets/` 或 `data/` 目录 + +**解决方法**： + +- 确保包放在 `extraloader/` 文件夹下的正确模式目录中 +- 检查包内容，确保包含必要的目录和文件 +- 查看 Minecraft 启动日志中的错误信息 + +### 2. 资源包图标显示为"未知来源" + +**原因**：包被标记为"未知来源" + +**解决方法**： + +- 检查包是否正确放置在 `extraloader/` 目录中 +- 确保 `pack.mcmeta` 文件格式正确 +- 查看控制台日志，确认包是否被正确加载 + +### 3. 系统全局包不生效 + +**原因**：`enableSystemGlobalPacks` 配置项被禁用 + +**解决方法**： + +1. 打开 `config/extraloader-common.toml` +2. 将 `enableSystemGlobalPacks` 设置为 `true` +3. 重启游戏 + +## 开发说明 + +### 目录约定 + +ExtraLoader 使用约定优于配置的设计理念： + +- **目录命名**：使用 `required`、`optional`、`default` 表示包的加载模式 +- **包识别**：根据包内容自动识别资源包/数据包类型 +- **配置简化**：通过简单的目录结构实现复杂的加载逻辑 + +### 日志级别 + +- `DEBUG`：包加载详细信息 +- `INFO`：包加载成功提示 +- `WARN`：无效的包被跳过 +- `ERROR`：包加载失败 + +## 许可证 + +MIT License + +## 贡献 + +欢迎提交 Issue 和 Pull Request！ From b72005447b518f609f434501d73588ac334a7319 Mon Sep 17 00:00:00 2001 From: Xin Luo <104831916+3453890470@users.noreply.github.com> Date: Fri, 20 Feb 2026 19:30:27 +0800 Subject: [PATCH 2/2] docs(readme): refine docs and add forum intro --- README.md | 205 ++++++++++---------------------------------------- WEB_INTRO.txt | 32 ++++++++ 2 files changed, 71 insertions(+), 166 deletions(-) create mode 100644 WEB_INTRO.txt diff --git a/README.md b/README.md index 6a4c293..35c91eb 100644 --- a/README.md +++ b/README.md @@ -1,195 +1,68 @@ # Extra Loader -一个 Forge 模组，通过约定优于配置的方式加载额外的资源包和数据包。 +Minecraft Forge 加载额外的资源包和数据包 -## 功能特点 +## 设计理念 -- **自动检测包类型**：根据包内是否包含 `assets/` 或 `data/` 目录自动识别资源包或数据包 -- **三种加载模式**： - - `required/` - 必须启用的包（红色标识，无法禁用） - - `optional/` - 可选包（青色标识，默认禁用） - - `default/` - 默认启用的包（绿色标识，可手动禁用） -- **支持多种包格式**：支持路径包（目录）和文件包（.zip/.jar） -- **系统级配置**：支持全局配置选项，管理包的启用/禁用 +Extra Loader 的目标是让 Mod 平台玩家更简单地管理游戏资源。通过将资源包集中存放在 `~/.extraloader//` 目录，玩家可以为不同版本的游戏维护独立的资源配置。我们提供三种加载模式（required/optional/default），让你对资源包的启用与禁用拥有灵活的控制权，既能确保关键资源必加载，也能避免不必要的包干扰游戏体验。 -## 兼容性 +### 存储目录 -- **Minecraft 版本**：支持所有 Minecraft 1.20+ 版本 -- **Forge 版本**：需要 Forge 1.20+ / NeoForge 1.20+ -- **Java 版本**：Java 17+ - -## 安装步骤 - -### 客户端安装 - -1. 下载 **ExtraLoader** 模组文件（JAR 格式） -2. 将模组文件放入 Minecraft 的 `mods/` 文件夹 -3. 启动游戏 - -### 服务端安装 - -1. 下载 **ExtraLoader** 模组文件（JAR 格式） -2. 将模组文件放入服务器上的 `mods/` 文件夹 -3. 启动服务器 - -> **注意**：ExtraLoader 仅在 Forge 1.20+ 环境中运行，不支持其他模组加载器。 - -## 目录结构 - -### 全局包目录 - -模组会在游戏目录下创建 `extraloader/` 文件夹： - -``` -<游戏目录>/ -└── extraloader/ - ├── required/ # 必须启用的包 - ├── optional/ # 可选包 - └── default/ # 默认启用的包 -``` - -### 系统全局包目录 - -模组还会在用户目录下创建系统级包目录： +将资源包或数据包放入对应目录： ``` -<用户目录>/ -└── .extraloader/ - └── / # 自动根据 Minecraft 版本创建子目录 - ├── required/ - ├── optional/ - └── default/ +~/.extraloader// +├── required/ # 必须加载 +├── optional/ # 默认禁用 +└── default/ # 默认启用 ``` -### 加载模式说明 - -| 模式文件夹 | 包的状态 | 颜色标识 | 是否可禁用 | -| ----------- | -------------- | -------- | ---------- | -| `required/` | 必须启用 | 红色 | 否 | -| `optional/` | 可选，默认禁用 | 青色 | 是 | -| `default/` | 默认启用 | 绿色 | 是 | - -### 包类型识别 - -ExtraLoader 会自动检测包的类型： - -- **资源包**：包含 `assets/` 目录的包 -- **数据包**：包含 `data/` 目录的包 +### 示例 -> **重要**：不需要在文件夹名称中指定 `resourcepacks/` 或 `datapacks/`，模组会根据包内容自动识别。 +**资源包**： -## 常用配置项 +- `~/.extraloader/1.20.1/required/my-pack.zip` +- `~/.extraloader/1.20.1/optional/bonus-textures/` -ExtraLoader 的配置文件位于 Minecraft 配置目录，包含以下配置项： +**数据包**： -### Common 配置 +- `~/.extraloader/1.20.1/default/nice-fonts.jar` -| 配置项 | 类型 | 默认值 | 说明 | -| ------------------------- | ------- | ------ | ---------------------- | -| `enableSystemGlobalPacks` | Boolean | `true` | 是否启用系统全局包目录 | +## 加载模式 -### Client 配置 +| 模式 | 行为 | 玩家可禁用 | +| ---------- | -------------------- | ---------- | +| `required` | 强制加载，缺失时跳过 | ❌ 否 | +| `optional` | 默认禁用，需手动启用 | ✅ 是 | +| `default` | 默认启用，可手动禁用 | ✅ 是 | -| 配置项 | 类型 | 默认值 | 说明 | -| ----------------------- | ---- | ------ | -------------------- | -| `disabledResourcePacks` | List | `[]` | 禁用的资源包 ID 列表 | +## 包识别规则 -### 配置文件示例 +- 包含 `assets/` → 资源包 +- 包含 `data/` → 数据包 +- 两者都有 → 同时加载 -`config/extraloader-common.toml`: +支持 `.zip`、`.jar` 文件或直接目录。 -```toml -enableSystemGlobalPacks = true -``` - -`config/extraloader-client.toml`: - -```toml -disabledResourcePacks = [] -``` - -## 使用示例 +## FAQ -### 示例 1：启用主题包 +**Q: 包没生效？** -1. 在 `extraloader/default/` 目录下放置主题包（.zip 或目录） -2. 包内容应包含 `assets/minecraft/textures/gui/title.png` -3. 启动游戏后，主题包会自动启用（绿色） +- 检查是否包含 `assets/` 或 `data/` 目录 +- 确认有 `pack.mcmeta` 文件 +- 路径是否正确（`~/.extraloader//`） -### 示例 2：使用强制资源包 +**Q: 如何禁用包？** -1. 在 `extraloader/required/` 目录下放置强制包 -2. 包内容应包含 `assets/minecraft/textures/` 目录 -3. 启动游戏后，强制包会自动启用且无法禁用（红色） +- `default`：游戏内手动禁用 +- `optional`：默认禁用，需手动启用 +- `required`：无法禁用，删除或移出该目录 -### 示例 3：禁用某个资源包 +**Q: 服务端要装吗？** -1. 打开 `config/extraloader-client.toml` -2. 在 `disabledResourcePacks` 列表中添加包的 ID： - -```toml -disabledResourcePacks = [ - "extraloader/default/example-theme.zip" -] -``` - -## 常见问题 - -### 1. 模组加载后看不到我的包 - -**可能原因**： - -- 包放在了错误的文件夹（如 `resourcepacks/` 而不是 `extraloader/default/`） -- 包缺少 `pack.mcmeta` 文件 -- 包内没有 `assets/` 或 `data/` 目录 - -**解决方法**： - -- 确保包放在 `extraloader/` 文件夹下的正确模式目录中 -- 检查包内容，确保包含必要的目录和文件 -- 查看 Minecraft 启动日志中的错误信息 - -### 2. 资源包图标显示为"未知来源" - -**原因**：包被标记为"未知来源" - -**解决方法**： - -- 检查包是否正确放置在 `extraloader/` 目录中 -- 确保 `pack.mcmeta` 文件格式正确 -- 查看控制台日志，确认包是否被正确加载 - -### 3. 系统全局包不生效 - -**原因**：`enableSystemGlobalPacks` 配置项被禁用 - -**解决方法**： - -1. 打开 `config/extraloader-common.toml` -2. 将 `enableSystemGlobalPacks` 设置为 `true` -3. 重启游戏 - -## 开发说明 - -### 目录约定 - -ExtraLoader 使用约定优于配置的设计理念： - -- **目录命名**：使用 `required`、`optional`、`default` 表示包的加载模式 -- **包识别**：根据包内容自动识别资源包/数据包类型 -- **配置简化**：通过简单的目录结构实现复杂的加载逻辑 - -### 日志级别 - -- `DEBUG`：包加载详细信息 -- `INFO`：包加载成功提示 -- `WARN`：无效的包被跳过 -- `ERROR`：包加载失败 +- 资源包仅客户端生效 +- 数据包需要服务端安装 ## 许可证 -MIT License - -## 贡献 - -欢迎提交 Issue 和 Pull Request！ +[MIT License](LICENSE) diff --git a/WEB_INTRO.txt b/WEB_INTRO.txt new file mode 100644 index 0000000..36d6794 --- /dev/null +++ b/WEB_INTRO.txt @@ -0,0 +1,32 @@ +[h1=核心功能] + +Extra Loader 是一个 Minecraft Forge 模组，用于集中管理资源包和数据包。无需手动复制到游戏目录，支持直接使用目录或 `.zip/.jar` 文件。 + +[h2=全局路径] + +instance 全局：`<游戏目录>/extraloader/` +system 全局：`C:\Users\[用户名]\.extraloader\[游戏版本]\` + +[h3=按功能分为:] + +`required` - 强制加载，始终生效，无法禁用（红色） +`optional` - 可选加载，默认禁用，玩家可手动启用（青色） +`default` - 默认加载，玩家可手动禁用（绿色） + +[h3=自动识别规则] + +包含 `assets/` → 资源包 +包含 `data/` → 数据包 +两者都有 → 同时加载 + +[h2=快捷命令] + +`/extraloader open instance` 与 `/extraloader open system` + +[h1=设计理念] + +免复制：无需手动将资源包复制到游戏目录 +跨整合包复用：同一版本的不同整合包可共享同一份资源包 +约定优于配置、开箱即用：按目录结构自动加载，无需额外配置 + +[ban:title_menu]