Tested with: KSA Version 2026.10.19.5638
This guide explains how to add custom 3D models as vehicles/parts in Kitten Space Agency (KSA).
The game directory depends on where the game was installed, see Directories and Files.
Inside it:
Content\Core\Meshes\Content\Core\Textures\Content\Core\Core*Assets.xml paired with Core*GameData.xml, plus the shared PartAssets.xml and PartGameData.xmlContent\Core\CoreEditorTagsGameData.xmlContent\Core\Reactions.xmlContent\Core\defaultvehicles\<Name>\Content\Core\EarthOnly.xml, EarthSystem.xml, SolSystem.xml, SolSystemDense.xmlFor your own parts, put your *Assets.xml in your mod folder and list it under assets in mod.toml. Editing Core's files directly works but gets overwritten on update.
KSA uses GLB (GLTF 2.0 binary) format for meshes.
Model Orientation:
Before exporting, orient your model according to KSA's coordinate system:
Examples:
In Blender:
your_model.glbKSA only renders the first primitive per mesh. If your model has multiple parts, you need to split them into separate GLB files.
Still true as of 2026.8.5.5168. Everything on the part rendering path takes primitive 0 of a mesh and ignores the rest, so a multi-primitive mesh silently loses everything after the first. Ground clutter objects are the one exception.
Mesh atlases do not get you out of this. Stock content ships one
*_MeshAtlas.glbper part pack, but an atlas is many separate meshes inside one file, not many primitives inside one mesh. Each<Mesh Id="...">still has to be single-primitive.
Split in Blender:
KSA uses PBR (Physically Based Rendering) materials with 3 texture types:
Diffuse (Base Color/Albedo) - Required
Normal (Tangent Space) - Required
AoRoughMetal - Required
<PbrMaterial> takes two more optional maps that stock parts use: <Emissive> for anything that glows, and <ThinFilm> for the heat-tinted metal look on nozzles and engine bells.
All stock part textures ship as .ktx2 atlases, one set per pack, for example
CorePropulsionA_TextureAtlas_Diffuse.ktx2. PNG is easier for a first mod.
If you don't have normal or AoRoughMetal textures, you need to create placeholder ones.
Flat Normal Map:
your_model_normal.pngNeutral AoRoughMetal Map:
your_model_roughmetalao.pngYou can create these in Photoshop, GIMP, or any image editor.
Copy all texture files (diffuse, normal, and AoRoughMetal) into a Textures folder inside your mod, next to the *Assets.xml that references them. Paths in the XML are relative to the mod folder.
In your mod's assets file:
<MeshFile Id="YourModelMesh" Path="Meshes/your_model.glb" Category="Vessel"/>
If you have multiple parts:
<MeshFile Id="YourBodyMesh" Path="Meshes/your_body.glb" Category="Vessel"/>
<MeshFile Id="YourHeadMesh" Path="Meshes/your_head.glb" Category="Vessel"/>
<MeshFile Id="YourLegsMesh" Path="Meshes/your_legs.glb" Category="Vessel"/>
In the same file, after the mesh definitions:
<PbrMaterial Id="YourModelMat">
<Diffuse Path="Textures/your_model_diffuse.png" Category="Vessel"/>
<Normal Path="Textures/your_model_normal.png" Category="Vessel"/>
<AoRoughMetal Path="Textures/your_model_roughmetalao.png" Category="Vessel"/>
</PbrMaterial>
For multiple parts with different textures, create multiple materials:
<PbrMaterial Id="YourBodyMat">
<Diffuse Path="Textures/your_body_diffuse.png" Category="Vessel"/>
<Normal Path="Textures/flat_normal.png" Category="Vessel"/>
<AoRoughMetal Path="Textures/neutral_roughmetalao.png" Category="Vessel"/>
</PbrMaterial>
<PbrMaterial Id="YourHeadMat">
<Diffuse Path="Textures/your_head_diffuse.png" Category="Vessel"/>
<Normal Path="Textures/flat_normal.png" Category="Vessel"/>
<AoRoughMetal Path="Textures/neutral_roughmetalao.png" Category="Vessel"/>
</PbrMaterial>
In the same file. Search stock Core*Assets.xml for other <Part Id= definitions to use as reference:
<Part Id="YourModelPart">
<SubPart Id="YourModelSubPart">
<PartModel Id="YourModelPartModel">
<Mesh Id="YourModelMesh"/>
<Material Id="YourModelMat"/>
</PartModel>
</SubPart>
</Part>
<Part Id="YourBodyPart">
<SubPart Id="YourBodySubPart">
<PartModel Id="YourBodyModel">
<Mesh Id="YourBodyMesh"/>
<Material Id="YourBodyMat"/>
</PartModel>
</SubPart>
</Part>
<Part Id="YourHeadPart">
<SubPart Id="YourHeadSubPart">
<PartModel Id="YourHeadModel">
<Mesh Id="YourHeadMesh"/>
<Material Id="YourHeadMat"/>
</PartModel>
</SubPart>
</Part>
<Part Id="YourLegsPart">
<SubPart Id="YourLegsSubPart">
<PartModel Id="YourLegsModel">
<Mesh Id="YourLegsMesh"/>
<Material Id="YourLegsMat"/>
</PartModel>
</SubPart>
</Part>
Verified against stock PartGameData.xml and CorePropulsionBGameData.xml (KSA 2026.7.9.5018). A single RCS thruster is a RocketThrusterController (binds a control axis to a Rocket) plus a Rocket (references a Combustor core and one or more DeLavalNozzle exits) plus the Combustor/Reaction/FeedsFrom machinery from the section above.
These four elements go alongside SubPart/EditorTag/Connector in the same SubPartGameData block matched by Id to your part's SubPart (see Building Player-Attachable Parts above) , not inside SubPart itself:
<SubPartGameData Id="YourModel_SubPart">
<!-- Binds a control axis to the Rocket below. ControlMap CSV names come from the list further down. -->
<RocketThrusterController Id="YawLeft">
<ControlMap CSV="YawLeft"/>
<RocketReference Id="YawLeft"/>
</RocketThrusterController>
<!-- One Core (combustion chamber) feeding one or more Nozzles. -->
<Rocket Id="YawLeft">
<Core Id="YawLeftCombustor"/>
<Nozzle Id="YawLeftNozzle"/>
</Rocket>
<Combustor Id="YawLeftCombustor">
<FeedsFrom Parent="true"/>
<Reaction Id="MMH_NTO">
<MixtureRatio>1.6</MixtureRatio>
</Reaction>
<MaxPressure Bar="7"/>
<ThermalEfficiency Value="0.75"/>
<MinimumPulseTime Seconds="0.008"/>
</Combustor>
<DeLavalNozzle Id="YawLeftNozzle">
<ExitDiameter M="0.02"/>
<AreaRatio Value="50"/>
<FlowEfficiency Value="0.72"/>
<ExpansionEfficiency Value="0.13"/>
<ExhaustLocation X="-0.2" Y="-0.15" Z="0.0"/>
<ExhaustDirection X="0.0" Y="1.0" Z="0.0"/>
<VolumetricExhaust Id="MmuRcsVac"/>
<SoundEvent Action="On" SoundId="DefaultRcsThruster"/>
</DeLavalNozzle>
<!-- Repeat the four-element group above per control axis for full 6-DOF control. -->
<!-- See stock PartGameData.xml (KittenBackPackSubPart) for a complete 6-axis example. -->
</SubPartGameData>
ExhaustLocation/ExhaustDirection coordinate system (same as the part's own +X-forward/+Z-up axes):
ExhaustDirection: Points opposite to thrust direction
Control Maps Available (ControlMap CSV=):
YawLeft, YawRight, PitchUp, PitchDown, RollLeft, RollRightTranslateForward, TranslateBack, TranslateLeft, TranslateRight, TranslateUp, TranslateDownReaction Id must match a MixtureReaction in stock Content/Core/Reactions.xml , MMH_NTO (hypergolic, no ignition needed , the stock convention for RCS) or Hydrolox are both valid; MixtureRatio is the propellant's oxidizer:fuel ratio for that reaction.
Craft are no longer defined in Astronomicals.xml. The old <Vehicle> block holding <RootPart>, <Mass>, <Orbit> and the rest is gone. VehicleTemplate reads four elements now and silently drops anything else, so a craft written the old way loads without an error and without appearing.
A craft is a folder under Content\Core\defaultvehicles\ holding a meta.toml and a vehicle.xml, with its starting orbit defined separately as a <Situation>.
The quickest route, once your parts load, is to build the craft in the editor and save it, then copy the saved folder out of Documents\My Games\Kitten Space Agency\vehicles\ into Content\Core\defaultvehicles\.
That also proves your Connector, EditorTag and MeshView work, because you cannot assemble the craft without them.
Full walkthrough including the hand-written XML: Adding a vehicle.
In your system file:
<LoadVehicleFromLibrary Id="YourVehicle" Parent="Earth">
<SituationRef InstanceOf="YourVehicleStartingSituation"/>
</LoadVehicleFromLibrary>
Not <LoadFromLibrary>, which only handles celestial bodies and will drop a craft without complaining.
See System.
Reflecting changes verified against KSA Version 2026.7.9.5018.
Everything above builds a static Vehicle that spawns pre-assembled via Astronomicals.xml. If instead you want a part players can pick up, attach, and build into their own rocket in the vessel editor (fuel tanks, engines, RCS blocks, command cores, etc.), the Part definition needs three more pieces:
A part with no <Connector> can't be stacked onto anything. Each connector is a node with a local Transform; connectors face +X by default, so the "back" connector needs a 180° flip to face outward:
<Part Id="YourEnginePart" DisplayName="Your Engine">
<SubPart InstanceOf="YourEngine_SubPart"/>
<EditorTag Value="Propulsion"/>
<Connector>
<Transform><Position X="0.5"/></Transform>
</Connector>
<Connector>
<Transform>
<Position X="-0.5"/>
<Rotation X="3.14159" Z="3.14159"/>
</Transform>
</Connector>
</Part>
Element order inside <Part> follows PartTemplate's schema, which runs roughly: SubPart, the rocket controllers, EditorTag, the engine cores (Rocket, Combustor, SolidMotor, ThermalCore, AntimatterRamCore), ConsumerFeedWiring, the nozzles (DeLavalNozzle, MagneticNozzle, SolidMotorNozzle), the mass geometry templates, Battery, Generator, SolarPanel, SolarTracker, PowerConsumer, MagneticScoop, DockingPort, PrimarySequenceModule, Diameter, EVADoor, Control, Connector, Grab, Aligned, SymmetryGroup, SubPartGroup, Thumbnail.
<Part> also takes an optional CrashTolerance attribute, in pascals: the contact pressure at which the part breaks. Leave it out and it is derived from the part's density. Core's engines use CrashTolerance="3e6" (30 bar).
Collider is not in that list. It is a module, along with MeshView, PartModel, PartModelDynamic, PartModelGlass, Light, Tank, FuelPort, IVASeat, AttachedInternal, KeyframeAnimationModule, SolidGrainSegment, Decoupler, GrabRail and Parachute. Decoupler used to be in both places and is now only a module; the XML is unchanged. A <Parachute> also gets ParachuteDeploy and ParachuteCut modules added automatically. See Parachutes.
A <Collider> module takes <Box>, <Sphere>, <Capsule>, <Cylinder> and, since 2026.8.19.5261, <ConvexHull> shapes. See Colliders. Modules are registered at runtime rather than declared on the class, so they do not occupy a fixed slot in the order.
The engine cores ThermalCore and AntimatterRamCore, the MagneticNozzle and the MagneticScoop are covered on Interstellar Engines.
PartTemplate's XmlSerializer silently ignores unknown elements, so a mod that wants its own data on a part has to re-parse the raw XML itself to read it back.
A bare <EditorTag Value="X"/> on a Part is no longer enough by itself. A matching EditorTagDef must also be declared once per tag, near the top of the Assets file:
<EditorTagDef Id="Propulsion"
RootPartWhitelist="true"
FaceSnapTargetWhitelist="true"
DiameterFilterlist="true" />
Without <EditorTagDef>:
<EditorTag> can't be selected as the vessel root (first part placed).<EditorTag> can't accept radial/face-snap attachments from other parts (e.g. an RCS block won't attach to the side of a probe core). Eventhough, connector-to-connector stacking (nose-to-base) still works.EditorTagDef attributes, all optional booleans/lists (default off):
| Attribute | Effect |
|---|---|
RootPartWhitelist |
Part can be placed as the vessel's first/root part |
FaceSnapTargetWhitelist |
Other parts can radially/face-snap attach to this part |
FaceSnapBlacklist |
This part is excluded from radial attachment entirely |
FaceSnapTargetBlacklist |
This part cannot itself be the target of a face-snap |
DiameterFilterlist |
Part is filtered/grouped by diameter tier in the parts list |
NotaCategory |
Tag is used for filtering only, doesn't create its own category tab |
Check stock Content/Core/CoreEditorTagsGameData.xml for the full set of stock tag defs (Structural, Command, etc.) as reference.
Two related breaking changes for engines and rocket cores:
1. Rocket cores need an explicit feed source. A RocketCoreTemplate with no feed point logs ERROR Rocket core X declares no FeedsFrom feed points; it will reach no propellant and produces no thrust:
<FeedsFrom Parent="true"/>
(or Container="..." / Connector="..." to feed from a specific part instead of the parent stack.)
2. Combustion was renamed to Reaction and changed type. The old SerializedReference form is gone:
<!-- OLD (pre-2026.7.9.5018) -->
<Combustion Id="Hydrolox_5.5"/>
<!-- NEW -->
<FeedsFrom Parent="true"/>
<Reaction Id="Hydrolox">
<MixtureRatio>5.5</MixtureRatio>
</Reaction>
Reaction Id must match a MixtureReaction Id defined in stock Content/Core/Reactions.xml (e.g. Hydrolox, Kerolox) , the mixture ratio moved out of the combined id string into its own <MixtureRatio> element.
A buildable part also needs a MeshView alongside its render mesh, or it can be placed but never re-selected in the editor:
<SubPart Id="YourPart_SubPart">
<PartModel Id="YourPart_PartModel">
<Mesh Id="YourPartMesh"/>
<Material Id="YourPartMat"/>
</PartModel>
<MeshView>
<Mesh Id="YourPartMesh"/>
</MeshView>
</SubPart>
When creating a part that also adds functionality, e.g. a reaction wheel, one has to combine creating a mod that adds the functionality and the part.
Add to the part xml:
<Part Id="YourMod_Part">
...
<YourModElement YourAttribute="42" .../> <!-- KSA ignores this -->
</Part>
Registry tracking parts using your mod functionality:
namespace YourMod
{
public static class YourModRegistry
{
public static void Register(string templateId, XElement yourModElement)
{
// Store reference to the part with part config data
}
}
}
The PartTemplate of KSA is closed, so it won't load any unknown types that are added to the part. It is necessary to create a patch class that will read the
using System.Xml.Linq;
using HarmonyLib;
using KSA;
namespace YourMod
{
[HarmonyPatch(typeof(Mod), "LoadAssetBundles")]
public static class YourModAssetPatch
{
// Mod.Assets is private (the [TomlField("assets")] file list); read it reflectively.
private static readonly FieldInfo? _assetsField = AccessTools.Field(typeof(Mod), "Assets");
public static void Postfix(Mod __instance)
{
if (_assetsField?.GetValue(__instance) is not string[] assetPaths)
return;
foreach (string assetPath in assetPaths)
ParseAssetFile(__instance.GetPath(assetPath));
}
private static void ParseAssetFile(string fullPath)
{
XDocument document;
try
{
document = XDocument.Load(fullPath);
}
catch (Exception)
{
// KSA already logs malformed asset XML; nothing to register here.
return;
}
if (document.Root == null)
return;
foreach (XElement part in document.Root.Elements("Part"))
{
string? templateId = part.Attribute("Id")?.Value;
if (string.IsNullOrEmpty(templateId))
continue;
// Register the part to you mod
// (Optional) Find your xml element in `part` and load the data needed.
YourModRegistry.Register(templateId, part.Element("YourModElement"));
}
}
}
}
Path="Meshes/your_model.glb" matches actual filename<PartRef> and <SubPartRef> nesting in the craft's vehicle.xmlExhaustDirection vectors on the DeLavalNozzle are correct<MaxPressure Bar="..."/> or <ExitDiameter M="..."/> on the Combustor/DeLavalNozzle (there is no direct Thrust N= value , thrust derives from chamber pressure, nozzle geometry, and the Reaction)Combustor's <FeedsFrom .../> actually reaches a tank (Parent="true" for the stack, or Container="TankId" for an onboard tank) , see the "RocketCore / Combustor propellant flow" section aboveRocketThrusterController's ControlMap CSV= value is one of the names listed above and its RocketReference Id matches the Rocket IdIf your model doesn't appear in-game, the GLB file's scene might be referencing the wrong node. This happens when Blender exports the scene pointing to an empty node instead of the node containing your mesh.
The scene reference needs to point to the node that has the mesh attached. You can use tools like glTF Viewer or custom scripts to inspect and fix the scene node references in your GLB file.