Tested with: KSA Version 2026.10.19.5638
Every mod needs a mod.toml sitting in its root folder. It is how the game finds out your mod exists and what it is supposed to load.
This page is the full list of keys. Most mods use three or four of them.
Documents\My Games\Kitten Space Agency\mods\
└── MyMod\
├── mod.toml
├── MyMod.dll
└── MyModAssets.xml
The folder name is the mod's id. That is the same id you write in manifest.toml to switch the mod on, and it is case-sensitive. MyMod and mymod are two different mods as far as the game's lookup is concerned. Match the folder name exactly.
The game's own content is a mod like any other: look at Content\Core\mod.toml for a working example of nearly every key on this page.
If your mod is pure code (a StarMap plugin with no XML), this is all you need:
name = "MyMod"
If it also ships assets:
name = "MyMod"
assets = [ "MyModAssets.xml" ]
These are the ones you will actually use. Every path is relative to your mod folder.
nameDisplay name for the mod. StarMap also matches this against your main class and DLL name, so keep all three the same.
name = "MyMod"
assetsXML files with an <Assets> root. This is where parts, materials, meshes, textures, sounds, planets, situations and everything else gets defined. Loaded in the order you list them, so if one file references an id from another, put the definition first.
assets = [
"MyModAssets.xml",
"MyModParts.xml",
"MyModGameData.xml",
]
See <Assets> Tag.
systemsXML files with a <System> root, one per star system you want to add to the system picker on the main menu.
systems = [ "MySystem.xml" ]
This is the key people forget. If your system does not show up in the list even though the mod is enabled and the XML is fine, it is almost always because it is missing here. See System.
starBinariesBinary star field files. Every enabled mod's star binaries stack on top of each other, including Core's, so yours adds stars rather than replacing them.
starBinaries = [ "MyStars.bin" ]
The binary format changed in 2026.10.13.5602, and binaries made before that will not load correctly. See Star Binaries.
fontsTTF files to add to the font dropdown in settings.
fonts = [ "MyFont.ttf" ]
planetMeshesXML files defining planet LOD mesh collections, the things a body references with <MeshCollection Id="..."/>. Core ships five.
planetMeshes = [ "MeshCollections/MyMeshCollection.xml" ]
planetRandomHeightmapCollectionsXML files defining random heightmap collections, used for procedurally varied terrain.
planetRandomHeightmapCollections = [ "TextureCollections/MyHeightmaps.xml" ]
These add options to the in-game settings menus. Like star binaries, every mod's entries are registered, so you are adding to the list rather than replacing it. Most mods have no reason to touch these, since Core already provides a sensible spread.
| Key | Type | What it does |
|---|---|---|
textureSizeCaps |
list of numbers | Texture resolution cap options. 0 means uncapped. |
supportedShadowMaps |
list of numbers | Shadow map resolution options. |
supportedThumbnailSizes |
list of numbers | Part thumbnail resolution options. |
simulationSpeeds |
list of numbers | Time warp multipliers, in seconds of sim per second of real time. |
textureSizeCaps = [ 0, 8192, 4096, 2048, 1024, 512, 256, 128 ]
supportedShadowMaps = [ 16384, 8192, 4096, 2048, 1024, 512 ]
supportedThumbnailSizes = [ 512, 256, 128, 64 ]
simulationSpeeds = [ 0, 0.1, 1, 2, 4, 10, 30, 120, 600, 1200, 3600, 14400, 86400, 604800, 2592000, 7776000, 31536000, 157680000, 315360000, 1576800000, 3153600000 ]
Five more quality settings take a name/value pair per option instead of a bare number:
| Key |
|---|
supportedCloudQuality |
supportedOceanSimQuality |
supportedExhaustQuality |
supportedKittenFurQuality |
supportedShadowSlots |
[[supportedCloudQuality]]
name = "Low"
value = 1
[[supportedCloudQuality]]
name = "High"
value = 3
[console] runs developer console commands automatically. Handy while iterating, because you can drop yourself straight into the camera position you are working on instead of flying there every launch.
[console]
onBoot = [ "someCommandAtStartup" ]
onLoad = [ "simspeed 1", "camera map 2.88 0.47 3635076" ]
onBoot runs once when the game boots.onLoad runs when a system finishes loading.Core uses onLoad to set the opening camera angle, which is why the game always starts looking at Earth the same way.
mod.toml only describes the mod. To actually load it, add it to manifest.toml in Documents\My Games\Kitten Space Agency\:
[[mods]]
id = "Core"
enabled = true
[[mods]]
id = "MyMod"
enabled = true
id is the folder name. Note the capital C on Core. The game writes this file itself when you toggle mods in-game, and it will use the real folder casing.
This is Content\Core\mod.toml, trimmed. It is the most complete working example there is:
name = "Core"
textureSizeCaps = [ 0, 8192, 4096, 2048, 1024, 512, 256, 128 ]
supportedShadowMaps = [ 16384, 8192, 4096, 2048, 1024, 512 ]
supportedThumbnailSizes = [ 512, 256, 128, 64 ]
simulationSpeeds = [ 0, 0.1, 1, 2, 4, 10, 30, 120, 600, 1200, 3600, 14400, 86400, 604800, 2592000, 7776000, 31536000, 157680000, 315360000, 1576800000, 3153600000 ]
# loaded for planet LODs
planetMeshes = [
"MeshCollections/DefaultMeshCollection.xml",
"MeshCollections/EarthScaleMesh.xml",
"MeshCollections/OceanMeshes.xml",
]
planetRandomHeightmapCollections = [ "TextureCollections/DefaultHeightmapCollection.xml" ]
systems = [ "SolSystem.xml", "SolSystemDense.xml", "EarthSystem.xml", "EarthOnly.xml", "SolSystemInterstellar.xml", "EarthOnlyInterstellar.xml" ]
assets = [
"CoreEditorTagsGameData.xml",
"DefaultAssets.xml",
"PartAssets.xml",
"CorePropulsionAAssets.xml",
"CorePropulsionAGameData.xml",
"Astronomicals.xml",
"Situations.xml",
"Sounds.xml",
"Reactions.xml",
# ...about forty in total
]
starBinaries = [ "stars_20byte.bin" ]
fonts = [ "JetBrainsMono-Regular.ttf" ]
[console]
onLoad = [ "simspeed 1", "camera map 2.88 0.47 3635076", "camera orbit -4.83 -0.41 2.85" ]
A missing key fails silently. If you forget
assets, your XML is simply never read. No error, no warning, the ids just do not exist. Same forsystems. When something "does nothing", checkmod.tomlbefore you start debugging the XML.
Content and not to the game root. assets = [ "MyModAssets.xml" ] means mods/MyMod/MyModAssets.xml.assets. A file that references an id defined in another file needs to come after it.MyMod_FuelTank) the way Core does (CoreFuelTankA_...).