Config files and settings
A mod keeps its options in one of two ways:
From Sunrise's modding bookead8a1e
| Config files | Settings | |
|---|---|---|
| Lives in | The game's config/ folder (on a server, serverconfig/ per world) | sunrise-mods/, one file per key |
| Edited by | The player, in a text editor | The player, on the mod's page in Options > Mods |
| You declare it with | Hooks:: | Registrar:: |
| You read it in | config_ and config_ | Host:: and the typed setting_ reads |
| NeoForge counterpart | ModContainer.registerConfig, ModConfigEvent | ModConfigSpec entries on the config screen |
Config files
Config files sit in the game's shared config/ folder, beside options.txt (beside server.properties on a dedicated server), as Fabric and NeoForge mods' do. Your mod picks its own names: a folder config/<mod id>/, or files config/<mod id>.<ext> and config/<mod id>-<rest>.
- In
register_configs, push each file with its kind (Client,CommonorServer) and the default text to write when the file is missing. Push all of them every time: each game reads only its own kinds. - The game reads each file and calls
config_loadingwith the mod id, the file and its text, which your mod parses (TOML by convention). Every mod hears every config, so check the mod id. - When the file changes on disk,
config_reloadingbrings the new text. The game checks modification times once a second; a save with the same text, a removed file or an unreadable one fires nothing and keeps the last text. - A
Serverconfig is per world: it loads beforeserver_about_to_startfrom the world'sserverconfig/, andconfig_unloadingdrops it afterserver_stopping.ClientandCommonconfigs load once and stay until the game quits.
These hooks run in the Config load phase: settings reads and config files are available, world handles and transactions are not. A file outside config/, or one already registered, is skipped.
For files the hooks don't manage, Host::config_files() gives your mod its own files in config/. Paths retain the ownership spelling above, such as <mod id>/extra.toml. The service is bound to the mod whose hook or Part is running; you cannot reach another mod's files.
Bulk data
Keep map tiles, waypoints, seeds and exports out of settings and config files:
Host::data_files()is available on both sides, rooted at<game directory>/sunrise-mod-data/<mod id>/. A client-only mod can key its own subfolders by server or save and dimension.ServerHost::world_data_files()is server-only, rooted at<world>/sunrise-mod-data/<mod id>/. Its contents are copied, deleted and backed up with the save. Without a current world it refuses calls withConfigFileError::NoWorld; a client has no world-folder service.
Both use the same ConfigFiles, ConfigPath, ConfigEntry and ConfigFileError types as config files, on native and wasm. Bulk paths are relative to your implicit mod root: tiles/overworld/0.bin, not <mod id>/tiles/overworld/0.bin. The game never scans bulk data as settings or config.
read, write and stat operate on checked /-separated paths; traversal (..), backslashes and symbolic links are refused. Writes replace the whole file atomically, never exposing partial contents. Sunrise's own per-file limits are DATA_FILE_MAX (64 MiB) for both bulk areas and CONFIG_FILE_MAX (4 MiB) for config files. Oversized files and unavailable operations return typed errors, rather than partially writing.
Walk a folder with list(&folder, after, limit): start with after = None, then pass the last returned entry's name as the exclusive cursor. Names are lexicographically ordered; each page has at most limit entries. limit must be between 1 and CONFIG_LIST_MAX (1024), or the call returns ConfigFileError::InvalidPage. Use ConfigPath::root() to list your own root, and stop when a page is empty.
Settings
Register each setting from Hooks::register with Registrar::register_setting(SettingSpec { … }): a key (a-z, 0-9, _, - and ., not starting with .), translation keys for its label and tooltip, and its kind with the default. A setting the spec check refuses, or a key you registered already, comes back as the error. Settings are client settings and appear on your mod's page in Options > Mods, opened from its Config button.
- Read a setting with
host.setting(mod_id, key)or a typed read. Typed reads are cached per data folder and key. host.set_setting(mod_id, key, value)keeps a value. A successful write updates the cache; a failed one leaves it. This write does not firesetting_changed.- When the player edits a setting, the value is kept first, then
setting_changedtells your mod alone.
A mod reads and writes only its own settings: another mod's id, or a key its owner never registered, reads None and writes nothing.
The settings folder is settings only, not bulk storage: ordinary files there are read as setting keys and subfolders or unsafe entries still warn during snapshots. Use the bulk services above instead; their files are not included in settings snapshots.
Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.



