OnBoot: content on the first start
Boot mods: statuses, effects, items, spells, talents and changes to the game's own data that are there before the game reads them, from the very first start.
New in 0.2.0-dev.28 on dedicated servers, and since 0.2.0-dev.29 in a player’s game too (a world they host and a game that joins a server). On dedicated test servers a mod built outside Kiln’s repository with the SDK patched 21 values of the game’s balancing table before the game read it. In a real game, a hosted world on 0.2.0-dev.28, More Flame Altars’
OnBootran and 42 values ofaltarsPerFlameLevelwere patched before the game read them (Where it runs).
The game reads some of its data once, when it starts: the programs behind statuses and spells, the skill tree, the
balancing table. What a mod defines in OnLoad comes too late for that first start; it is there from the second one.
Mod.OnBoot runs earlier, before the game reads any of it. What a boot mod stages there is in the game from the very
first start, with the same ids a Define in OnLoad gives it.
For players this means: a mod that adds items, spells or talents has them on a server’s first start, with no second restart, and a mod that changes values the game reads once (experience per level, Flame Altars per base) works from the first start too. Before, its change came too late.
Turning it on
In kiln.mod.json (see the manifest):
{ "id": "frost-tokens", "boot": true } // or "required"
From a project, <KilnBoot>true</KilnBoot> (or required) writes "boot" into the generated kiln.mod.json.
true: the mod’sOnBootruns. If its boot content fails, this mod (and the mods that require it) is left out and named in kiln.log; the server starts without them. A broken boot mod never half-loads."required": a start stops with a clear message when the mod’s boot content can’t be applied, instead of loading a world without it. Use it when a world without your content would be worse than no server: a world that already holds your items, for example.
What OnBoot does
public override void OnBoot(BootContext boot)
{
var defs = BootDefinitions.For(boot);
defs.Define("chill", new StatusBlock { Name = "Chill", Seconds = 6 });
defs.Define("frost-token", new ItemBlock { Name = "Frost Token", Stack = 50 });
}
Add Blocks to KilnServices. OnBoot runs once per start, before the game, on a copy of your mod that is thrown away
when it returns. The instance that later gets OnLoad is a new one: nothing you keep in a field survives. Hand
everything over by staging it.
- Five kinds of block can be staged in this release: statuses, effects, items, spells and talents, plus
resource patches. Any other kind answers
NotInBootKinds; define it inOnLoador a data file, where it works as a runtime block. - A refusal is a result,
Okfalse with aReason:DuplicateDefinition,PhaseClosed(staged afterOnBootreturned),TooMany(more than 4096),NotInBootKinds.Okmeans staged, not yet in the game. - References. A boot definition can name one the same
OnBootstaged before it, not another mod’s block and not one of your ownblocks/*.json(BootReferenceOutside). - A data file wins. A
blocks/*.jsonblock of the same kind and name is used, and the staged one is dropped with a warning. - Nothing of the running game. There is no tick, world or player yet.
Blocks.Definethrows (stage withBootDefinitions.For(boot).Defineinstead), and a call that needs the game’s tick says which member refused and that it belongs inOnLoad.
Settings in OnBoot
Config.Register<T>() and its Value work in OnBoot, so a boot mod can stage with a number from its settings:
public override void OnBoot(BootContext boot)
{
var altars = Config.Register<Settings>().Value.Altars; // the file's value, else the default
BootDefinitions.For(boot).Define("more-altars", new ResourcePatchBlock
{
Resource = Guid.Parse("82706b40-61b1-4b8f-8b23-dcec6971bda1"),
Type = "keen::BalancingTable",
Set = { ["altarsPerFlameLevel[*]"] = ResourceValue.AtLeast(altars) },
});
}
Register again in OnLoad: the running mod keeps that one, and it sees the same values OnBoot read. Writing a
setting, Reload and Changed are for OnLoad; in OnBoot they say so. A file edited between the two is read again,
and kiln.log says OnBoot used the earlier values.
Settings and joining players
New in 0.2.0-dev.29. Each game and each server makes its boot content once, at its start, from its own settings, and
nothing syncs it later. A player whose settings of your mod differ from the server’s has other game data: the server’s
values decide, while the player’s game shows and predicts its own (a server set to 8 Flame Altars, a player set to 4).
So the join compares them. For each boot mod with side both, both sides send a fingerprint of what their boot content
committed (the staged definitions and the mod’s resource patches, also those in blocks/*.json), and the server treats a
difference like another version of the mod:
modSync on the server |
A player whose boot content differs |
|---|---|
refuse |
is turned away: “The boot content of More Flame Altars on your game differs from this server’s … Use this server’s settings of More Flame Altars and restart the game.” |
warn, or not set |
joins, with that warning on the Kiln menu’s Network page and in their kiln.log |
off |
nothing is compared |
The player takes the server’s settings of the mod (its file in kiln/config, from the server’s operator or its
modpack) and restarts the game: a config sync or a reload can’t change boot content. Not compared: an older Kiln on
either side, a mod in optionalMods, a mod with side client or server, and another version that the server’s
versionMatch lets in.
So read in OnBoot only settings a server and its players share, such as balance values the server sets for everyone,
and say on your mod’s page that players take the server’s. A setting that may differ per player belongs in OnLoad.
Stage the same content for every role too: content that depends on boot.Roles differs between a player’s game and a
dedicated server, and the join counts that as a difference. Not yet seen between a real server and a real game.
The game’s data in OnBoot
boot.GameData (IReadOnlyGameData) reads the game’s own items, templates, skill nodes and materials, as they
shipped:
var logs = boot.GameData.Read("item:Material_T1_Wood_Logs"); // also template:, skill:0x…, material:
The game hasn’t loaded anything yet, so the answers come from the boot snapshot: a copy of those records that Kiln
makes from the game’s files. The launcher makes it when it starts the game with an enabled mod that has "boot":
half a minute to a minute and about 300 MB, once per game update. On a server you start yourself, run
kiln boot-snapshot --game <server folder>.
Any resource (0.2.0-dev.29.17). names:resources/<qualified type name> lists every resource of a type
(names:resources/keen::SceneResource), and resource:<GUID>/<type>/<part> reads one of any type, not only items and
templates. The snapshot holds them since 0.2.0-dev.29.17 (that is why it grew from about 200 MB); an older snapshot is
made again once, at the next start through the launcher.
- Without a snapshot of this game build,
mods.boot.game_datais off andReadthrowsKilnUnavailableException. A mod that can do without it checksCapabilities.Is("mods.boot.game_data")first and keeps its own defaults. - Starting from Steam makes no snapshot: it uses one that is there already. Start the game through the launcher
once, or run
kiln boot-snapshot, for each game version. - The snapshot shows the game’s own values: not another loader’s patches, and not resource patches (they are written later).
Resource patches
A boot mod can change fields of the game’s data before the game reads them: the balancing table’s experience per level, or Flame Altars per flame level. In a blocks file:
{
"format": 1,
"resourcePatches": {
"more-altars": {
"format": 1,
"resource": "82706b40-61b1-4b8f-8b23-dcec6971bda1",
"type": "keen::BalancingTable",
"set": {
"altarsPerFlameLevel[*]": { "min": 16 },
"experienceNeedPerLevel[0]": 1500
}
}
}
}
Or in OnBoot, with a ResourcePatchBlock:
BootDefinitions.For(boot).Define("more-altars", new ResourcePatchBlock
{
Resource = Guid.Parse("82706b40-61b1-4b8f-8b23-dcec6971bda1"),
Type = "keen::BalancingTable",
Set =
{
["altarsPerFlameLevel[*]"] = ResourceValue.AtLeast(16),
["experienceNeedPerLevel[0]"] = 1500,
},
});
This is the way for a mod that raises the number of Flame Altars a base may have. A change made in OnLoad came too
late for such data: the game had already read it.
| Path | Means |
|---|---|
playerLevelCap |
a member |
a.b.c |
a member of a nested struct |
list[3] |
element 3 of a list (counted from 0) |
list[*] |
every element, however many this game build has |
| Value | Result |
|---|---|
1500, 0.5, true, "EnumName" |
the member is set to it |
{ "mul": 2 }, { "add": 5 } |
the game’s value times 2, plus 5 |
{ "min": 16 }, { "max": 100 } |
at least 16, at most 100 |
The keys combine: the game’s value times mul, plus add, then held between min and max. A path ends in a
number, a bool or an enum; strings and references to other resources can’t be patched.
Lists and template components
New in 0.2.0-dev.29.15. Besides set, a patch can change the shape of a resource:
| Key | On | Does |
|---|---|---|
append |
a list of numbers, bools or enum members | adds values at its end; "aboveLast": true adds only values greater than the list’s last, so a sorted list stays sorted |
addComponents |
a template | gives it components of these game types, zeroed; one it already has stays as it is |
removeComponents |
a template | takes out components of these types; what an actor needs to live is refused |
"ground-pickup": {
"resource": "9bf5aac3-6ae0-43b1-9f27-18c2f98abfca",
"type": "keen::ecs::TemplateResource",
"removeComponents": ["SpawnTime"],
"addComponents": ["PickupItemZone"],
"set": { "PickupItemZone.lastAttempt.value": 0, "Gravity.isActive": false }
},
"more-steps": {
"resource": "46e14df6-fb8f-4f66-9463-e23b9e19e48e",
"type": "keen::FbUiBundle",
"append": { "difficultySettings.settingValues.enemyDamage.steps": { "values": [3, 5, 10], "aboveLast": true } }
}
On a template a path starts with a component’s type name (Gravity.isActive; Gravity#1.isActive for a second one):
that is how an added component’s fields are filled in. Name components by type, never by their place in the list. In C#:
RemoveComponents, AddComponents and Append (with ResourceListAppend { Values = [3, 5, 10], AboveLast = true })
on the ResourcePatchBlock.
Since 0.2.0-dev.29.17 three more:
| Key | On | Does |
|---|---|---|
copyComponents |
a template | { "<component type>": "<template GUID>" }: copies the whole component, with all its data, from that other template. Added when the template has none of that type, its own replaced when it has. The source is read as the game has it, before any patch of this start |
clear |
lists of anything | ["<list path>", …]: each list made empty |
replace |
a list of numbers, bools or enum members | { "<list path>": { "values": [ … ] } }: the list holds exactly these values afterwards, fewer or more than before |
"area-deposit-chest": {
"resource": "65baa890-022a-454b-9cb7-b92cb8c06cd4",
"type": "keen::ecs::TemplateResource",
"copyComponents": { "InventoryCraftingStock": "955ba32f-08ea-414d-bd98-ac75990aef04" }
},
"damage-steps": {
"resource": "46e14df6-fb8f-4f66-9463-e23b9e19e48e",
"type": "keen::FbUiBundle",
"replace": { "difficultySettings.settingValues.enemyDamage.steps": { "values": [0.25, 0.5, 1, 2, 4] } }
}
(The first gives an ordinary storage chest the Magic chest’s crafting stock component.) In C#: CopyComponents,
Clear and Replace (with ResourceListReplace). A list path of clear, replace or append names one list: [i]
on the way is fine, [*] is not.
The order. On one resource every patch’s removeComponents come first, then every patch’s addComponents, then
copyComponents, clear, replace, append and last set, each group in load order. The order in which a patch
writes its keys doesn’t matter. Two mods are combined when they can’t step on each other; when they can (both clear or
replace one list with different values, one clears a list another appends to or sets inside, one copies a component and
another counts on what it held), the later mod in the load order is refused before the game starts, and the report names
both. Another mod’s plain value set on a copied component is fine.
A patch applies whole or not at all (since 0.2.0-dev.29.15): if any of its changes fails, none is kept, and the
resource is what the other patches make it. kiln.log and kiln/state/boot.json name the mod, the patch and the reason.
Finding records by name. In OnBoot, the game-data queries names:items, names:templates, names:skills and
names:materials list the names a kind holds, names:templates/<component type> (names:templates/MiningNode)
the templates with that component, and since 0.2.0-dev.29.17 names:resources/<type> every resource of a type
(The game’s data in OnBoot).
- Checked before the start: the type, the path and the value. Two mods on one field are not combined: the later in the load order is refused, and the report names both.
- Written when the game’s resource service is up and nothing has read from it yet. A patch that fails then is in
kiln.log and
kiln/state/boot.json, and the start goes on without it. A required boot mod’s patch that can’t be applied stops the start instead, with the reason in boot.json. - Both sides need the mod. A patch changes the data of the game it runs in. A player who joins without the mod
keeps the game’s values on their side, so what their game shows can differ from what the server does. A mod that
patches data both sides read says
"clients": "mod". Since 0.2.0-dev.29 a boot mod loads in a player’s game too, and the join compares the two sides’ boot content (Settings and joining players). - A blocks file with
resourcePatchesmay have comments (//,/* */) and trailing commas, like every blocks file. - The game’s own limits still hold. The game never allows more than 16 Flame Altars, whatever the table says.
- A patch lasts while the game runs. It isn’t written to disk or into a save.
Afterwards
Mods.BootState(id)says whether a mod’s boot content made it:Committedmeans its definitions are in the game.BootDefinitionsCommittedEventcomes once after eachOnLoad, when the committed definitions are active. Subscribe inOnLoad.Blocks.Findfinds a block yourOnBootstaged as soon as the boot content is committed: inOnLoad, by name from other blocks (Applies = new StatusApply { Status = "chill" }), and after the mod unloads.Blocks.DefineinOnLoadunder the name of a committed boot block: the same block gives back the committed one; a different block is refused withRestartRequiredBoot. What is in the game can’t change before a restart: change it inOnBootand restart.- After a change, restart. At the start Kiln keeps a record of every file in a boot mod’s folder and of the settings
its
OnBootread. Unloading the mod and loading it again works while those are as they were. A changed file or a changed setting is refused withRestartRequiredBoot, naming the files or the setting (altars: 4 -> 6): restart the game or the server. A reload of a loaded boot mod is always refused the same way. - Not a change: a JSON file written again with the same values (other spacing, comments), Kiln rewriting the settings
file, files whose name starts with
., and what the mod and Kiln write into the mod’s data folder. Don’t write into your own mod folder while the game runs: such a file counts. - A boot mod enabled after the start loads at the next start.
- Icons of staged items, statuses and game-tree talents are files in your mod’s folder with a relative path, as in
OnLoad(Visual = new VisualBlock { Icon = "icons/token.png" }), and show from the first start since 0.2.0-dev.29; before, a boot-staged item or talent kept the icon of the one it was made from. A missing file, or a path that leaves the folder, costs only the icon: kiln.log says so once and the SDK’s bake warns (KILN030). - Reading a boot mod’s files costs a little time at the start, about 1 s per 300 MB.
When a boot mod fails
OnBootthrows, or a staged definition doesn’t compile: the mod is out, with none of its definitions or files, and so is every mod that requires it. kiln.log names it.- A bad entry in the mod’s own files (an
assets/assets.jsonentry with a bad GUID or a missing file, ablocks/*.json,skills/*.jsonorquests/*.jsonthat isn’t JSON or can’t be read): Kiln logs it and leaves that entry out; the rest of the mod loads, as without OnBoot. - With
"required"the mod gets all of its boot content or the start stops: a failedOnBoot, a refused definition, and also one bad entry in its own files. No world or save is loaded. The process ends with exit code0x4B01(on Linux, under Wine, the exit status is 1). The last line of kiln.log names the mod, the file or entry and why, andkiln/state/boot.jsonhas the same. - What only the game’s data or a loading world shows stops a required mod’s start later, still before a player is in the world: a resource patch that can’t be written, a skill node the tree build leaves out, an item, recipe or clone the world doesn’t register.
Where it runs
- Dedicated servers since 0.2.0-dev.28.
- A player’s game, a world they host and a game that joins a server, since 0.2.0-dev.29, with no setting: the rows
mods.boot.clientandmods.boot.resource_patchesare open. In 0.2.0-dev.28 a boot mod didn’t load there unless"preview"was set inkiln/kiln.json; that setting is no longer needed, and leaving it does no harm. A server that runs a boot mod its players need no longer turns away players who have Kiln and the mod. - A player’s game builds every mod’s VFX and material files at its start, as it always did. Staging VFX or materials
in
OnBootis not in this build (mods.boot.vfxreads unavailable, “not in this build”, on a client). A required boot mod with a broken VFX or material file stops the start in a player’s game too, and the stop line names the file; an optional boot mod loses only that file, with a line in kiln.log. - A boot mod’s resource patches are never lost without notice: if the game’s resource service was up before the boot content was ready, the mod is left out (or the start stops for a required one) and kiln.log says why.
- A server where the boot phase doesn’t run (safe idle, .NET off) doesn’t load boot mods either; the row
mods.boot.phasesays why.
Next to other loaders’ mods in a player’s game, boot mods were confirmed in one hosted game; the guided check of both loader orders has not been played yet.
Testing
KilnHarness.BootPhase in Kiln.TestKit runs your OnBoot under dotnet test, with the same staging as a start:
Tests without the game. The SDK’s bake runs it too: a build fails
(KILN032) when OnBoot throws or a definition would not lower. The sample boot-gallery stages a status, an effect,
an item, a spell, a talent and a resource patch, and reads the game’s data.