Tested with: KSA Version 2026.10.19.5638
This guide explains how to add custom star binaries to the game.
The format changed in 2026.10.13.5602. Each star is now 20 bytes instead of 16, and the header has a second field. Binaries made for older builds will not load correctly and must be regenerated. If your mod ships a
.bin, rebuild it.
Content\Core\*.bin. Core loads stars_20byte.bin, a community-made binary built from the AT-HYG catalogue. hip_main.bin, generated from the Hipparcos catalogue, also ships and is the commented-out alternative in Core's mod.toml.Content\Sample\star_import_manifest.tomlStar binaries are, like the name says, binary files (.bin). You can either generate one from a catalogue with the in-game generatestarbinary command (the easy way, see below), or write the bytes yourself.
All numbers in star binaries use little-endian byte order.
| Offset | Type | Meaning |
|---|---|---|
| 0 | int32 |
Number of stars in the file |
| 4 | float32 |
Magnitude scale. Controls how much brighter a star draws as you fly towards it. |
The magnitude scale is the brightness.magnitudeScale value from the import manifest. Core's binary uses 0.15, hip_main.bin uses 0.13. Only one value can be active: if several mods load binaries with different scales, the last binary loaded wins and the game logs a warning saying so.
| Offset | Type | Meaning |
|---|---|---|
| 0 | 3 × float32 |
Direction to the star as a unit vector, in KSA's ecliptic coordinate conventions |
| 12 | uint8 |
Sprite size, 0 to 128 |
| 13 | 3 × uint8 |
Colour, RGB 0 to 255 |
| 16 | float32 |
Inverse distance in 1/parsecs. 0 means unknown distance. |
The inverse distance is what lets stars move against the background and grow brighter as you approach them. A star with 0 stays fixed on the sky at any position, like the old format behaved.
Sizes above 128 are clamped to 128 on load, with one warning per binary saying how many were clamped. The star shader cannot draw larger sprites. For reference, Sirius in the Hipparcos import comes out at 121.
This is an example of a binary that creates one large blue star on the positive X axis, 10 parsecs away (inverse distance 0.1):
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00000000 01 00 00 00 9A 99 19 3E 00 00 80 3F 00 00 00 00 ........?.......
00000010 00 00 00 00 80 00 00 FF CD CC CC 3D ...........=
That is: count 1, magnitude scale 0.15, direction (1, 0, 0), size 128, colour (0, 0, 255), inverse distance 0.1.
The game can build a binary for you from a delimited text catalogue, such as the HEASARC hip_main.dat.
Documents\My Games\Kitten Space Agency\stars\mystars.dat..toml extension (mystars.toml). Copy Content\Sample\star_import_manifest.toml as a starting point and set the column indexes for your catalogue.generatestarbinary stars\mystars.dat. The path is relative to the Game Documents Directory.mystars.bin.The manifest keys:
| Key | What it does |
|---|---|
starScale |
Overall sprite size multiplier |
delimiter |
Column separator character |
brightness.magnitudeScale |
Spread between bright and dim stars. Also written into the header. |
brightness.magnitudeOffset |
Shifts overall brightness |
brightness.dimStart / brightness.dimEnd |
Stars dimmer than dimStart are faded towards dimEnd |
rightAscension.column |
Column index for right ascension, in degrees |
declination.column |
Column index for declination, in degrees |
magnitude.column |
Column index for apparent magnitude |
distance.column |
Column index for distance |
distance.parallax |
true if that column is a parallax in milliarcseconds, false if it is a distance in parsecs |
bvColor.column |
Column index for the B-V colour index |
bvColor.minimum |
Stars whose colour falls below this are dropped |
Rows with a zero, negative or non-numeric distance are kept, with an unknown distance. Rows where any other column fails to parse are skipped silently, so compare the "generated N stars" line in the log against your catalogue's row count.
Delete the old
.binbefore regenerating. The generator opens the output without truncating it, so writing a smaller binary over a larger one leaves the old file's tail behind.
The generator does not apply the 128 size cap itself. If your starScale is high, the brightest stars will be written larger than 128 and clamped when the game loads them. Lower starScale until the load warning goes away.
Edit the mod.toml file to include
starBinaries = ["YOUR_FILE"]
ATTENTION: every mod including Core will stack their star binaries on top of each other (like shown in the example).

This screenshot was taken with the old 16-byte format. The result looks the same.
If your system places a real star as a <StellarBody> (see Multiple Star Systems), the background star at the same spot would draw twice. The game hides catalogue stars that fall inside a sphere around each star body, sized at 2% of the star's distance from Sol by default. Set <StarMaskRadius> on the body to change that, and use the starmask console command to list which catalogue stars each body hides.
This only works for stars in the binary that have a distance. Stars with inverse distance 0 are never hidden.