跳转到内容

Mod 设置

设置页面应在持久化数据注册之后,从 Mod 初始化入口注册。

RitsuLibFramework.RegisterModSettings("MyMod", page => page
.WithTitle(ModSettingsText.Literal("My Mod"))
.WithModDisplayName(ModSettingsText.Literal("My Mod"))
.AddSection("general", section => section
.WithTitle(ModSettingsText.Literal("通用"))
.AddToggle(
"enabled",
ModSettingsText.Literal("启用"),
new ModSettingsValueBinding<MySettings, bool>(
"MyMod",
"settings",
SaveScope.Global,
s => s.Enabled,
(s, value) => s.Enabled = value))
.AddIntSlider(
"volume",
ModSettingsText.Literal("音量"),
new ModSettingsValueBinding<MySettings, int>(
"MyMod",
"settings",
SaveScope.Global,
s => s.Volume,
(s, value) => s.Volume = value),
minValue: 0,
maxValue: 100)));

固定文本使用 ModSettingsText.Literal(...)。需要本地化时,使用 ModSettingsText.I18N(...) 或 ModSettingsText.LocString(...)。

控件Builder 方法
开关AddToggle
整数滑条AddIntSlider
浮点滑条AddSlider
选项 / enumAddChoice、AddEnumChoice
颜色AddColor
单行文本AddString
多行文本AddMultilineString
按键绑定AddKeyBinding、AddMultiKeyBinding
按钮AddButton
可编辑列表AddList
只读内容AddHeader、AddParagraph、AddInfoCard、AddImage、AddRuntimeHotkeySummary
嵌套页面AddSubpage
自定义 Godot 控件AddCustom

每个交互控件都应有稳定 entry id。发布后改 id 会破坏剪贴板和 UI 元数据预期。

保存在 ModDataStore 中的字段使用 ModSettingsValueBinding<TModel,TValue>。临时 UI 使用 InMemoryModSettingsValueBinding<TValue>。

当控件编辑较大对象的一部分时,用 ProjectedModSettingsValueBinding<TSource,TValue> 包装父绑定。

var settingsBinding = new ModSettingsValueBinding<MySettings, MySettings>(
"MyMod", "settings", SaveScope.Global, s => s, (_, value) => value);
var volumeBinding = new ProjectedModSettingsValueBinding<MySettings, int>(
settingsBinding,
"volume",
s => s.Volume,
(s, value) => { s.Volume = value; return s; });

只在特定界面有意义的设置,可以限制可见性或只读状态:

page
.WithVisibleOnHostSurfaces(ModSettingsHostSurface.MainMenu | ModSettingsHostSurface.RunPause)
.WithReadOnlyOnHostSurfaces(ModSettingsHostSurface.CombatPause);

运行时条件使用 WithVisibleWhen 和 WithEnabledWhen。