服务端配置项

基本信息

属性 值
配置类 serverutils.ServerUtilitiesConfig
源码 src/main/java/serverutils/ServerUtilitiesConfig.java:23-847
字段总数 138（全部 public，全部带 @Config.Default*）
本页覆盖 109（不含 Commands 的 29 条，见 指令开关配置）
顶层分组 17 个（:28-46）
配置系统 GTNHLib com.gtnewhorizon.gtnhlib.config.Config
目录 configSubDirectory = "../serverutilities/"（:23）

计数方法

字段数用三种独立方式交叉验证，结果一致为 138：

方法 结果
grep -c "@Config\.Default" ServerUtilitiesConfig.java 138
@Config.Default* 注解类型求和（101 bool + 4 double + 5 enum + 1 float + 12 int + 1 intList + 6 string + 8 stringList） 138
逐行匹配「public + 非 static final + 非 class」字段并检查其前 8 行内是否有 @Config.Default* 138（全部字段 100% 覆盖）

@Config.Ignore 标注的字段（如 AFK.notificationTimer、Login.motdComponents）全部是 private，不出现在统计中。

分组分布

分组 行 字段数 本页
general 48-68 4 ✓
teams 70-100 7 ✓
debugging 102-143 10 ✓
auto_shutdown 145-163 3 ✓
afk 165-195 3 ✓
chat 197-206 2 ✓
commands 208-297 29 见 指令开关配置
backups 299-367 14 ✓
login 369-430 4 ✓
ranks 432-446 3 ✓
world 448-713 36 ✓
tasks.cleanup 715-750 7 ✓
pregen 752-765 2 ✓
mixins 768-789 4 ✓
motd 791-807 3 ✓
transfer 809-818 2 ✓
tab 820-846 5 ✓

[!IMPORTANT] WorldConfig 的 36 个字段分散在 3 层：本体 24 个、WorldLogging 子类 9 个（:450-493）、RulesFlip 子类 3 个（:497-515）。world.flip 字段以 @Config.Name("flip_game_rules_when_empty") 暴露（:517），world.logging 字段是 final 对象（:495）。

各类配置项

general（4 项）

字段 行 类型 默认 说明
merge_offline_mode_players 53 EnumTristate TRUE 合并离线模式玩家的 profile；DEFAULT 表示仅单人游戏合并
enable_pause_when_empty_property 57 boolean true 回移植 1.20 的 pause-when-empty-seconds
enable_max_tick_time_property 63 boolean true 回移植 1.8 的 max-tick-time
enable_toggle_cheats_button 67 boolean true 世界选择界面加「切换作弊」按钮

teams（7 项）

字段 行 默认 说明
disable_teams 75 false 完全禁用队伍
autocreate_mp 79 false 多人游戏按用户名+随机色自动建队
autocreate_sp 83 true 单人/LAN 自动建或加入 ID 为 singleplayer 的队
hide_team_notification 87 false 隐藏「无队伍」提示
grief_protection 91 true 领地内禁止他人破坏方块
interaction_protection 95 true 领地内禁止他人交互方块
force_team_prefix 99 false 强制聊天前缀为队名

disable_teams 带 @Config.Sync（:74）。

debugging（10 项）

全部默认 false。

字段 行 说明
special_commands 106 启用调试指令（控制 /add_fake_player）
print_more_info 110 输出更多信息
print_more_errors 114 输出更多错误
log_network 118 记录收发网络封包
log_teleport 122 记录玩家传送
log_config_editing 126 记录配置编辑
dev_sidebar_buttons 130 显示仅开发用的侧边栏按钮
gui_widget_bounds 134 按住 B 显示 GUI 控件边界
log_events 138 记录所有 EventBase 事件
log_chunkloading 142 每次区块强制加载/卸载都打控制台（注释明确建议关闭，防刷屏）

auto_shutdown（3 项）

字段 行 类型 默认 说明
enabled 150 boolean false 启用定时关机
enabled_singleplayer 155 boolean false 单人世界也启用
times 162 String[] {"04:00", "16:00"} HH:MM 格式，取最近的未匹配时刻

enabled 与 enabled_singleplayer 复用 serverutilities.config.enabled 语言键（:149、:154）。

afk（3 项）

字段 行 类型 默认 说明
enabled 170 boolean true 启用 AFK 计时
enabled_singleplayer 175 boolean true 单人世界也启用
notification_timer 179 String "5m" 超时多久后向全体广播

getNotificationTimer()（:188-194）惰性地用 Ticks.get(notification_timer).millis() 解析并缓存到 @Config.Ignore private long notificationTimer（:181-182）。

chat（2 项）

字段 行 默认 说明
add_nickname_tilde 201 false 改过昵称的玩家名前加 ~ 防钓鱼
replace_tab_names 205 true TAB 列表显示聊天中使用的昵称

backups（14 项）

字段 行 类型 默认 范围 说明
enable_backups 303 boolean true — 启用备份
backup_timer 308 double 0.5 min=0 备份间隔（小时），0.5 = 每 30 分钟
backups_to_keep 313 int 12 min=1 保留的备份数
compression_level 318 int 1 0..9 0 不压缩，1 最快，9 最小
backup_folder_path 322 String "./backups/" — 备份目录
additional_backup_files 326 String[] {"saves/NEI/global/**", "saves/NEI/local/$WORLDNAME/**"} — 额外打包路径
use_separate_thread 330 boolean true — 独立线程执行（注释标注「推荐」）
display_file_size 334 boolean true — 完成后打印（当前大小 | 总大小）
need_online_players 338 boolean true — 无玩家在线时跳过备份
silent_backup 342 boolean false — 除严重错误外静默
max_folder_size 349 int 0 min=0 备份目录上限 GB；0 = 禁用改用 backups_to_keep
delete_custom_name_backups 353 boolean true — 删除 /backup start <name> 起的自定义名备份
only_backup_claimed_chunks 359 boolean false — 只备份已领取区块（更快更小，未领取区块不可恢复）
backup_entire_regions_with_claims 366 boolean false — 整区域备份完整 .mca；依赖上一项

additional_backup_files 的注释（:324）说明支持 / 分隔符、* 通配、$WORLDNAME 变量，指定目录须以 /** 结尾。

login（4 项）

字段 行 类型 默认 说明
enable_motd 373 boolean false 启用进服欢迎语
enable_starting_items 377 boolean false 启用初始物品
motd 382 String[] {"Hello player!"} 欢迎语行
starting_items 387 String[] {id:"minecraft:stone_sword",Count:1,Damage:1,tag:{display:{Name:"Epic Stone Sword"}}} 初始物品 NBT

motd 带 @Config.Reloadable("login_motd")（:380），可单独重载。getStartingItems()（:409-429）逐条用 ItemStackSerializer.parseItem 解析，失败只打 LOGGER.warn 不中断（:421-423），结果缓存在 @Config.Ignore private List<ItemStack> startingItems（:392-393）。

ranks（3 项）

字段 行 默认 说明
enabled 437 true 启用 Rank 权限体系
override_chat 441 true 覆盖聊天颜色/等级专属格式
command_permissions 445 true 为指令添加权限节点，交由 rank 控制

world（36 项）

本体字段（24 项）

字段 行 类型 默认 范围/说明
chunk_claiming 523 boolean true 启用领地（带 @Config.Sync）
chunk_loading 527 boolean true 启用区块强制加载；chunk_claiming 为 false 时无效
safe_spawn 531 boolean false 出生点保护：禁爆炸与敌对生物、禁玩家互伤
spawn_area_in_sp 535 boolean false 单人世界也启用出生点区域
blocked_claiming_dimensions 539 int[] {} 禁止领地的维度 ID
enable_pvp 547 EnumTristate DEFAULT DEFAULT=玩家自选 / TRUE=全开 / FALSE=全关
enable_explosions 555 EnumTristate DEFAULT 同上语义，针对爆炸
enable_endermen 564 EnumTristate DEFAULT 需 chunk_claiming 与 mixins.endermen 同时为真
spawn_radius 568 int 0 注释要求把 server.properties 的 spawn-protection 设为 0
spawn_dimension 572 int 0 出生点维度，默认主世界
unload_erroring_chunks 576 boolean false 维度未加载等问题导致报错时卸载区块
rtp_min_distance 580 double 1000D /rtp 最小距离
rtp_max_distance 584 double 100000D /rtp 最大距离
rtp_max_tries 588 int 200 /rtp 最大尝试次数
disabled_right_click_items 595 String[] {""} 语法 modid:item:metadata，metadata 填 * 忽略；实际解析按 @ 切分（见下）
forced_spawn_dimension_time 606 int -1 min=-1, max=23999；-1 禁用 / 0 早晨 / 6000 正午 / 12000 傍晚 / 18000 午夜
forced_spawn_dimension_weather 616 int -1 min=-1, max=2；-1 禁用 / 0 晴 / 1 雨 / 2 雷暴
disable_player_suffocation_damage 620 boolean false 卡墙时不受伤害
show_playtime 624 boolean false 角落显示游戏时间
enable_player_sleeping_percentage 629 boolean true 启用睡觉百分比跳过夜晚
player_sleeping_percentage 634 int 50 0..100；仅是 gamerule 的初始值，非生效值
vampire_sleep_percent 639 int 50 0..100；棺材中吸血鬼需达到的百分比
blockMobSpawningInClaims 647 EnumTristate DEFAULT 领地内是否阻止刷怪
mobTypesToBlock 654 String[] {"AMBIENT","WATER_CREATURE","MOB","ANIMAL"} 仅 blockMobSpawningInClaims=TRUE 时生效

[!WARNING] disabled_right_click_items 的配置注释说语法是 modid:item:metadata（:591-593），但实际解析代码用 s.split("@", 2)（:684）——即真正生效的分隔符是 @ 而非 :。这是注释与实现不一致，按实现为准。

enable_player_sleeping_percentage 带 @Config.ModDetectedDefault(coremod = "ganymedes01.etfuturum.mixinplugin.EtFuturumEarlyMixins", value = "false")（:628）—— 检测到 Et Futurum 时默认值自动改为 false（因为该模组自带同功能）。

world.logging（9 项，ServerUtilitiesConfig.java:450-493）

字段 行 默认 说明
enabled 455 false 启用世界日志
include_creative_players 459 false 记录创造模式玩家
include_fake_players 463 false 记录假玩家
block_placed 467 true 记录放方块
block_broken 471 true 记录破坏方块
item_clicked_in_air 475 true 记录空中点击物品
entity_attacked 479 true 记录攻击其他玩家/实体
exclude_mob_entity 483 true 排除生物
chat_enable 487 false 记录聊天

log(EntityPlayerMP)（:489-492）是统一的判定入口：enabled && (include_creative_players || 非创造) && (include_fake_players || 非假玩家)。

world.flip（3 项，暴露名 flip_game_rules_when_empty，:497-518）

字段 行 类型 默认 范围
enable_flip_game_rules_when_empty 503 boolean false 服务器空时翻转指定游戏规则
flip_game_rules_when_empty_seconds 508 int 60 0..86400
flip_game_rules_when_empty_rules 514 String[] {""} 规则名，如 doDaylightCycle, doWeatherCycle

:499-501 的注释警告：翻转状态在重启后保留，禁用该功能前应先在未翻转状态下停服。

tasks.cleanup（7 项，ServerUtilitiesConfig.java:715-750）

字段 行 类型 默认 说明
enabled 722 boolean false 启用定期实体清理
interval 726 double 2 清理间隔（小时）
hostiles 730 boolean true 清理敌对生物
passives 734 boolean false 清理友好生物
items 738 boolean true 清理地面掉落物
experience 742 boolean true 清理经验球
silent 746 boolean false 静默清理前的警告

pregen（2 项）

字段 行 类型 默认 说明
chunksPerTick 756 int 1 每 tick 排队生成多少区块
timeLimitMs 760 float 25 每 tick 预生成时间上限（毫秒）；注释指出区块卸载耗时不受此限制

timeLimitNanos()（:762-764）做 timeLimitMs * 1_000_000 转换。

mixins（4 项，@Config.RequiresMcRestart，:767-789）

字段 行 默认 说明
endermen 776 true 启用地中海幽灵行为 Mixin（world.enable_endermen 的前置）
bypassPlayerLimit 780 true 添加 serverutilities.bypass_player_limit 节点
farmlandTramplingProtection 784 true 让防破坏保护也覆盖耕地踩踏
modernTabOverlay 788 true 现代风格 TAB 覆盖层（玩家头颅、动态列、header/footer）

mixins.modernTabOverlay 是互斥开关：REPLACE_TAB_NAMES 的 setApplyIf 是 !mixins.modernTabOverlay（mixin/Mixins.java），MODERN_TAB_OVERLAY 的 setApplyIf 是 mixins.modernTabOverlay。

motd（3 项）

字段 行 类型 默认 说明
enabled 796 boolean false 启用自定义服务器 MOTD
line1 801 String §6§lMy Minecraft Server 支持颜色码与 {players} {maxPlayers} {tps} {memory} {uptime}
line2 806 String §aUptime: §f{uptime} §7| §bTPS: §f{tps} 同上

line1/line2 都带 @Config.Reloadable("server_motd")（:800、:805）。

transfer（2 项）

字段 行 类型 默认 说明
enabled 813 boolean true 启用 /transfer 指令与切换封包
whitelist 817 String[] {} 允许的主机名白名单；空 = 全部允许

tab（5 项，全部带 @Config.Sync）

字段 行 类型 默认 说明
showPlayerHeads 825 boolean true 显示玩家头颅图标
showPingNumber 830 boolean true 显示数字延迟（如 42ms）
showPingBars 835 boolean true 显示信号格
headerText 840 String &b&lGTNH Server\n&7A modern tab list for 1.7.10 用 & 颜色码，\n 换行；可被代理插件频道覆盖
footerText 845 String &7Ping: &a< 150ms &e< 300ms &c< 600ms &4< 1000ms &8>= 1000ms\n&8Powered by &dServerUtilities 同上

外部读取者

按「声明 → 赋值 → 是否有外部读取」三段核验，全部 138 个字段都通过 GTNHLib ConfigurationManager.registerConfig(ServerUtilitiesConfig.class)（core/ServerUtilitiesCore.java:24）反射生成配置文件，并由以下外部读取者消费：

  • ServerUtilitiesCommands.registerCommands（command/ServerUtilitiesCommands.java:28-175）读 commands.*、auto_shutdown.enabled、general.enable_pause_when_empty_property、transfer.enabled、debugging.special_commands
  • serverutils.mixin.Mixins 枚举的各 setApplyIf lambda 读 ranks.enabled、ranks.command_permissions、mixins.*、commands.back、commands.vanish、motd.enabled、world.enable_player_sleeping_percentage、general.enable_pause_when_empty_property、general.enable_max_tick_time_property、general.enable_toggle_cheats_button
  • task/backup/BackupTask、task/CleanupTask、task/ShutdownTask、task/DecayTask 读 backups.*、tasks.cleanup.*、auto_shutdown.*、afk.*
  • WitcheryCompat / Mixins.CANCEL_VAMPIRE_WAKEUP_EVENT 读 world.vampire_sleep_percent
  • client/ServerUtilitiesClient 与 client/gui/* 读 tab.*（经 @Config.Sync 下发）

相关条目