Skip to content

Server Config

Jump to bottom
Tsu edited this page Jun 5, 2026 · 2 revisions

Server Config

Stratum does not piggyback on vanilla server config. It loads its own config files at startup and keeps the main config split into sidecars.

Source of Truth

  • Config model: sources/VintagestoryLib/Vintagestory.Server/StratumConfig.cs
  • Config load/save: sources/VintagestoryLib/Vintagestory.Server/StratumRuntime.cs
  • Startup wiring: sources/VintagestoryLib/Vintagestory.Server/ServerSystemStratum.cs

Files

  • stratum.json
  • stratum-commands.json
  • stratum-performance.json

StratumRuntime.LoadOrCreateConfig sets those paths under the game config folder and saves them back out after load.

ConfigPath = Path.Combine(GamePaths.Config, "stratum.json");
CommandsConfigPath = Path.Combine(GamePaths.Config, "stratum-commands.json");
PerformanceConfigPath = Path.Combine(GamePaths.Config, "stratum-performance.json");

if (!File.Exists(ConfigPath))
{
    Config = StratumConfig.CreateDefault();
    SaveConfig();
}
else
{
    string json = File.ReadAllText(ConfigPath);
    Config = JsonConvert.DeserializeObject<StratumConfig>(json) ?? StratumConfig.CreateDefault();
    if (File.Exists(CommandsConfigPath))
    {
        Config.Commands = JsonConvert.DeserializeObject<StratumCommandsConfig>(File.ReadAllText(CommandsConfigPath)) ?? new StratumCommandsConfig();
    }
    if (File.Exists(PerformanceConfigPath))
    {
        Config.Performance = JsonConvert.DeserializeObject<StratumPerformanceConfig>(File.ReadAllText(PerformanceConfigPath)) ?? new StratumPerformanceConfig();
    }
    Config.EnsurePopulated();
    SaveConfig();
}

Startup Wiring

ServerSystemStratum.OnBeginConfiguration is where Stratum loads config and applies the startup-only pieces:

bool loaded = StratumRuntime.LoadOrCreateConfig(server, out string message);
if (StratumRuntime.Config.Diagnostics.LogStartupSummary)
{
    LogStartupSummary(loaded, message);
}

StratumBlockEntityInitConfig beInit = StratumRuntime.Config.Performance.BlockEntityInit;
BlockEntity.StratumDefaultInitialDelaySpreadMs = (beInit != null && beInit.Enabled) ? beInit.MaxStaggerMs : 0;

That same method also applies the timer-resolution setting and optional startup preflight.

OnBeginRunGame then wires runtime services and identity config keys (stratum, stratumVersion, stratumBaseGameVersion).

Top-Level Sections

StratumConfig is split into these areas:

  • Diagnostics
  • Hardening
  • PacketLimits
  • PacketBackPressure
  • BlockBreakGuards
  • ClientModPolicy
  • Performance
  • Commands
  • Chat
  • Theme
  • CrowdSpawn
  • LoadTesting
  • LoginProtection
  • PlayerPrivacy
  • Nametags
  • Network

The config also carries a ConfigVersion and a small migration step for older configs.

Versioning

Current default config version is 2. The migration code only touches values that match the old default exactly, so custom settings stay custom.

if (ConfigVersion < 2)
{
    StratumPhysicsConfig phys = Performance?.Physics;
    if (phys != null)
    {
        if (phys.ParallelThreshold == 256) phys.ParallelThreshold = 32;
    }
    ConfigVersion = 2;
}

Practical Reading

If you want to understand what a setting does, the order is:

  1. The JSON default in StratumServer/stratum.default.json
  2. The config class in StratumConfig
  3. The runtime class that consumes it
  4. The patch file that changes the live behavior

Related References

Clone this wiki locally