CoreTweaks 配置

[!INFO] 实现类：makamys.coretweaks.Config（纯静态字段 + 注解） 加载器：makamys.coretweaks.util.AnnotationBasedConfigHelper 配置文件：config/coretweaks.cfg（硬编码路径） 条目数：53 个活跃配置项

配置文件路径

File configFile = new File(Launch.minecraftHome, "config/coretweaks.cfg");
boolean configFileExisted = configFile.exists();
Configuration config = new Configuration(configFile, CoreTweaks.VERSION);
config.load();
configHelper.loadFields(config);

⚠️ 路径硬编码为 config/coretweaks.cfg，不可通过配置改。 Configuration 构造时传入 CoreTweaks.VERSION 作为配置版本， 配合 ConfigMigrator 做版本迁移。

Config.reload() 被调用 3 处：

调用点 时机
MixinConfigPlugin.onLoad Mixin 插件加载（最早）
CoreTweaksPlugin 构造器 coremod 实例化
CoreTweaksMod.onConstruction @Mod 构造阶段
CoreTweaksMod.onServerAboutToStart 服务端启动前（重载）

即单客户端运行中配置会被读取 3~4 次（onServerAboutToStart 在客户端不触发）。

核心机制：三值 FeatureSetting

本模组的每个功能开关都是 FeatureSetting（包装枚举 Setting）， 不是普通 boolean。这是理解全部配置的关键。

public static enum Setting { FALSE, TRUE, FORCE; }

isActive() 的判定：

public boolean isActive() {
    return setting != Setting.FALSE
        && (setting == Setting.FORCE || (setting == Setting.TRUE && !disabled));
}
配置值 行为
false 关闭
true 开启，但若被冲突检测 disable() 则仍关闭
force 无条件开启，绕过冲突检测

配置文件顶部的说明（由 setCategoryComment("_categories", …) 写入） 也明确了这一点：A feature toggle can be set to the following values. If a different value is provided, the setting will be reverted to the default setting on next start.

disabled 标记

FeatureSetting.disable() 把 disabled = true，由 Config.shouldDisable 在配置加载期调用（见 功能兼容矩阵）。 force 是唯一能绕过它的取值。

类别总开关

setValue 会额外读一个 _categories 分类下的 enable<Category> 键：

config.getBoolean("enable" + capitalize(ann.cat().toLowerCase().split("\\.")[0]),
                  "_categories", true,
                  "Set this to false to disable all features in the '<category>' category.")

即设置 enableOptimizations=false 可一键关闭整个 Optimizations 分类。 取的是分类名的第一段（split("\\.")[0]），故 Optimizations.transformerCache.full 也归 enableOptimizations 管。

6 个配置分类

分类 项数 内容
Optimizations 11 启动/类加载性能
Bugfixes 11 上游 bug 回移修复
Tweaks 9 行为调整
Optimizations.Mods 2 OptiFine / FastCraft 专属优化
Tweaks.Mods 2 OptiFine 专属调整
Diagnostics 2 诊断辅助

另有 7 个子分类用于分组附加参数： Optimizations.transformerCache[.full|.lite]、 Tweaks.tweakCloudHeightCheck、Tweaks.clampFarPlaneDistance、 Optimizations.jarDiscovererCache、 Optimizations.excludeLibraryTransformation、 Diagnostics.detect_data_watcher_id_conflicts、 Bugfixes.fixIntelRendering。

53 个配置项的注解分布

注解 数量 承载类型
@ConfigWrappedEnum 37 FeatureSetting
@ConfigBoolean 4 boolean
@ConfigInt 4 int
@ConfigString 3 String
@ConfigEnum 2 CloudHeightCheck / TransformerCache
@ConfigStringList 2 StringList
@ConfigFloat 1 float

37 个功能开关 + 16 个参数项 = 53。

⚠️ 3 个功能被硬编码为 FALSE（注解被注释）

以下字段带注释掉的注解 + 硬编码 FeatureSetting.FALSE， 用户无法在配置文件中启用：

字段 注释掉的注解 影响
clientChunkMap @ConfigWrappedEnum(… def=FALSE …)（WIP，从 1.16 移植） 2 个 Mixin 永不可达
threadedTextureLoader @ConfigBoolean(… def=FALSE …)（“Use multi-threaded texture loading…? Placebo.”） 2 个 Mixin + 整条加载器路径死代码
coreTweaksCommand @ConfigBoolean(… def=TRUE …) /coretweaks 不可用

coreTweaksCommand 尤其矛盾：注释里写的默认值是 TRUE， 字段却是 FALSE；且注释声明 @ConfigBoolean 而字段类型是 FeatureSetting —— 取消注释也无法编译。

因此「53 个配置项」中，这 3 项实际不可配置。

关键参数默认值

配置 类型 默认 说明
minFarPlaneDistance float 180f 远平面钳制下界
cloudHeightCheckMode enum VARIABLE_CORRECTED 云渲染三态
transformerCacheMode enum LITE 变换器缓存模式
jarDiscovererCacheMaxAge int 8 缓存最大存活轮次（-1 无限）
badTransformers String org.spongepowered.asm.mixin.transformer.Proxy,appeng.transformer.asm.ApiRepairer,com.mumfrey.liteloader.transformers.ClassOverlayTransformer+ FULL 模式下需恢复 transformer 链视图的名单
badClasses String net.eq2online.macros.permissions.MacroModPermissions 不缓存的类
modFilesToIgnore String CMD files.jar 触发缓存重建时忽略的文件
recentCacheSize int 512 保留最近 N 份字节码（-1 永久）
verbosity int 1 0=精简 / 1=保存时打印 / 2=调试
transformersToCache StringList 5 个 FML/CodeChicken 变换器 LITE 模式缓存名单
liteTransformerCacheMaxSizeMB int 128 LITE 缓存上限（-1 无限）
lateLiteTransformerCache boolean false DEFAULT 阶段才挂钩（更安全）
useDiffsInTransformerCache boolean true 只存差分，体积减 40~70%
excludeLibraryTransformationPackages StringList gson/joptsimple/netty/trove/kotlin 变换排除前缀

useDiffsInTransformerCache 的取舍

配置注释给出量化数据：只存差分使缓存体积减少 40~70%， 但命中时转换慢约 25%，首次创建慢 50~100%。 resetOnLoad = true 标注在 excludeLibraryTransformationPackages 上， 使该默认值每次启动重置。

StringList 的 :resetOnLoad 机制

StringList.set 会剥掉以 :resetOnLoad 开头的首元素：

this.list = Arrays.copyOfRange(list,
    list.length > 0 && list[0].equals(":resetOnLoad") ? 1 : 0, list.length);

getRaw() 返回含标记的原始数组，get() 返回剥离后的列表。

配置文件注释的 3 处笔误

reload() 中的 setCategoryComment：

  1. "In this config file, every feature toggle has the name of '_enabled'." —— 实际键名由 categoryProperty = "_enabled" 决定， 拼写是 _enabled（下划线在后），此处描述不准确。
  2. "If a different value is provided, the setting will be reverted to the default setting on next start." —— 对 force 之外的非法值成立。
  3. "* appliable" 拼写错误（应为 applicable）， 出现在 transformer_cache.full 与 .lite 两处分类注释中。

另外分类注释里的键名写作 Optimizations.transformer_cache.full （下划线），而实际字段注解用的是 cat = "Optimizations.transformerCache.full"（驼峰）—— 注释与实际分类名不一致。

相关条目