星影配置

星影配置

星影配置构建模组

工具

★ Starshadow Config

从纯 Java 类生成精美的配置界面。

Starshadow Config 是一个面向 Fabric 模组的注解驱动配置库。将你的设置定义为一个简单的 Java 类,为字段添加注解,即可获得一个精美的配置界面——包含标签页、分区、滑块、开关和枚举下拉菜单——无需编写任何样板 UI 代码。

“配置界面不应该需要 GUI 编程博士学位。”


🪄 工作原理

面向模组开发者

  1. 添加依赖到你的 build.gradle.kts
  2. 创建配置类并为字段添加注解
  3. 完成 —— Starshadow Config 会自动生成整个界面
@StarConfig(modId = "mymod")
public class MyConfig {
    @Tab(id = "general", icon = "minecraft:crafting_table")
    @Section("scanning")
    @Range(min = 1, max = 64)
    @DefaultValue("16")
    private int scanRange = 16;

    @Section("display")
    @DefaultValue("true")
    private boolean showOverlay = true;
}

就是这样。无需界面构建类。无需控件定位。无需布局计算。只需你的配置字段和注解。

面向玩家

如果某个模组使用了 Starshadow Config,你将获得:

  • 可通过 Mod Menu 访问的标签式设置界面
  • 在所有使用该库的模组中保持干净、一致的 UI
  • 使用滑块、开关和下拉菜单,而不是原始文本输入框
  • 用于恢复默认值的重置按钮

✨ 特性

📝 注解驱动 API

为你的配置 POJO 添加注解,界面便会自行构建:

  • @StarConfig —— 将类标记为配置
  • @Tab —— 将字段分组到带图标的标签页中
  • @Section —— 将字段组织到带标签的分区中
  • @Range —— 设置数值字段的最小值/最大值
  • @DefaultValue —— 定义默认值
  • @EnabledWhen —— 根据其他值有条件地启用字段
  • @Hidden —— 从生成的界面中排除字段
  • @Widget —— 覆盖默认控件类型

🔨 流式构建器 API

需要更多控制?使用 StarConfigBuilder 实现完全编程式的方式:

StarConfigBuilder.create("mymod")
    .parent(parentScreen)
    .tab("general", tab -> tab
        .icon(Items.CRAFTING_TABLE)
        .section("scanning", section -> section
            .intSlider("scanRange", b -> b
                .range(1, 64).defaultValue(16)
                .binding(() -> config.scanRange,
                         v -> config.scanRange = v))
        )
    )
    .onSave(() -> serializer.save())
    .build();

💾 JSON 持久化

GsonConfigSerializer 负责以可读的 JSON 格式加载和保存配置文件。文件按照 Fabric 约定存储在 config/<mod-id>.json 中。

🎛️ 丰富的控件类型

  • 开关 用于布尔值
  • 滑块 用于带范围的数值
  • 步进器 用于整数值
  • 枚举循环 用于枚举选择
  • 字符串字段 用于文本输入
  • 描述条目 用于信息性文本

🔗 Mod Menu 集成

通过一个类即可注册你的配置界面:

public class MyModMenuIntegration implements ModMenuApi {
    @Override
    public ConfigScreenFactory<?> getModConfigScreenFactory() {
        return ModMenuConfigFactory.create("mymod", MyConfig.class, MyConfig::get);
    }
}

🧩 条件字段

使用 @EnabledWhen 创建依赖型设置,当条件不满足时这些设置会变灰:

@EnabledWhen(field = "pacingMode", notEquals = "ADAPTIVE")
private int linesPerSecond = 4;

📦 安装

面向模组开发者

添加到你的 build.gradle.kts:

dependencies {
    modstitchModImplementation("com.starshadow:starshadow-config:${property("starshadow_version")}")
    modstitchModImplementation("com.starshadow:starshadow-lib:${property("starshadow_version")}")
    include("com.starshadow:starshadow-config:${property("starshadow_version")}")
    include("com.starshadow:starshadow-lib:${property("starshadow_version")}")
}

面向玩家

Starshadow Config 已捆绑在使用它的模组中——你通常不需要单独安装它。如果某个模组需要它作为外部依赖:

  1. 为你的 Minecraft 版本安装 Fabric Loader
  2. 安装 Fabric API
  3. 将 Starshadow Config 和 Starshadow Lib 的 .jar 文件放入你的 mods/ 文件夹
  4. 启动 Minecraft

支持: Minecraft 1.20.1 · 1.20.4 · 1.21.1 —— 仅限 Fabric


🧩 兼容性

模组 兼容性
Fabric API ✅ 必需
Mod Menu ✅ 可选 —— 配置界面注册(如果安装了 Starshadow Menu 则不需要)
Starshadow Menu ✅ 可选 —— 配置界面发现
Cloth Config ✅ 可共存 —— 不同的配置系统

📋 要求

依赖 是否必需?
Fabric Loader ✅ 是
Fabric API ✅ 是
Starshadow Lib ✅ 是
Mod Menu 或 Starshadow Menu 可选 —— 任一均可提供配置界面访问

🌟 配置从此简单

不再编写数百行配置界面代码。Starshadow Config 将你的配置类自动转变为精美、功能完善的设置界面。


由 Ghent Starshadow 用 ❤️ 制作 基于 MPL-2.0 许可 —— 可自由使用、分享和修改。