配置 API

基本信息

属性 值
接口全名 mcp.mobius.waila.api.IWailaConfigHandler
源码 src/main/java/mcp/mobius/waila/api/IWailaConfigHandler.java（44 行）
唯一实现 mcp.mobius.waila.api.impl.ConfigHandler（ConfigHandler.java:18）
配置文件 event.getSuggestedConfigurationFile()（ConfigHandler.java:144）
配置分区 general / modules / server_forcing（Constants.java:40-41）

功能

IWailaConfigHandler 是注入到每一个 provider / decorator / 渲染器回调中的第 4（或第 3）个参数。4 个方法：

方法 返回 用途
getModuleNames() Set<String> 所有已注册的配置分区名（ConfigHandler.java:46-48）
getConfigKeys(String modName) HashMap<String,String> 指定分区的全部 key→显示名；分区不存在时返回 null（ConfigHandler.java:51-54）
getConfig(String key) boolean 读配置，省略默认值时用 Constants.CFG_DEFAULT_VALUE
getConfig(String key, boolean defvalue) boolean 读配置并指定默认值

Constants.CFG_DEFAULT_VALUE 恒为 true（Constants.java:17），因此 addConfig(modname, key) 不带 defvalue 的重载默认全为 true（ModuleRegistrar.java:77-79、ModuleRegistrar.java:87-89）。

读取优先级

ConfigHandler.getConfig(String, boolean) 的判定顺序（ConfigHandler.java:96-104）：

  1. 服务端未安装且该 key 属服务端强制类 → 返回 false（ConfigHandler.java:98）
  2. forcedConfigs 命中 → 返回强制值（ConfigHandler.java:100）
  3. 否则读 modules 分区并取 boolean（ConfigHandler.java:102-103）

第 1 步意味着：用 addConfigRemote 声明的 key 在纯客户端环境下恒为 false，因为 Waila.instance.serverPresent 保持 false（Waila.java:54，全类中除 checkModList 外无赋值）。这是设计如此，不是 bug。

服务端强制分区

server_forcing 分区由 addConfigRemote 系列填充（ModuleRegistrar.java:102-104 → ConfigHandler.addConfigServer，ConfigHandler.java:82-89）。配置文件内注释写明用途（ConfigHandler.java:176-177）：

Any key set to true here will ensure that the client is using the configuration set in the ‘module’ section above. This is useful for enforcing false to ‘cheating’ keys like silverfish.

modules 分区的对应注释见 ConfigHandler.java:174-175。

数值

项 值 来源
接口方法数 4 IWailaConfigHandler.java
CFG_DEFAULT_VALUE true Constants.java:17
SERVER_FREE false Constants.java:42
配置分区数 3（general / modules / server_forcing） Constants.java:40-41、ConfigHandler.java:146-172
addon 声明的 module 配置项总数 36 见 模块配置项

交互

配置声明流程：IWailaRegistrar.addConfig* → ModuleRegistrar → ConfigHandler → 写入 modules 与 server_forcing 两个分区（ConfigHandler.java:56-64）。免反射声明通道见 IMC 注册入口。general 分区的键值与默认值见 通用配置项。

相关条目