Sprite scaling for item mods

Why your custom item renders too big, off-center, or without an inventory icon — and how to fix each symptom.

The three symptoms

When a custom item's PNG doesn't match what the game expects, you'll see a consistent trio of problems:

• Too big on the ship floor. The item sprite fills several tiles when it should occupy one or two.
• Off-center on the tile. The item renders shifted relative to its socket footprint.
• No inventory icon, or a stretched/wrong-size icon. The item shows a blank or garbled cell in inventory grids.

All three trace back to a mismatch between two independent measures: the logical footprint (how many inventory-grid tiles the item occupies, derived from your JSON data) and the visual footprint (the pixel size of the source PNG, interpreted against a hard-coded tile-pixel constant). This page covers both, plus the inventory icon and normal-map fields that are easy to miss, and a section on installable items that need a separate sprite for their uninstalled (inventory) form.

How logical footprint works

The game reads an item's tile dimensions at load time from two fields on the item's items/ entry (the JsonItemDef struct):

nCols

Width in tiles. Integer; defaults to 1 if omitted. Confirmed in JsonItemDef.cs constructor: this.nCols = 1.

aSocketAdds

Array of loot-table strNames, one entry per body-socket slot. Length of this array divided by nCols gives the height in tiles. Single-tile items have one entry; a 2-tile-tall item has two entries for each column.

The C# that performs this calculation is at Item.cs:271-272:

this.nWidthInTiles  = this.jid.nCols;
this.nHeightInTiles = this.aSocketAdds.Count / this.jid.nCols;

// Item.cs lines ~265-272 (inside Item.SetData / load path)
this.bHasSpriteSheet = this.jid.bHasSpriteSheet;
if (this.jid.ctSpriteSheet != null)
{
    this.ctSpriteSheet = DataHandler.GetCondTrigger(this.jid.ctSpriteSheet);
}
this.nWidthInTiles  = this.jid.nCols;
this.nHeightInTiles = this.aSocketAdds.Count / this.jid.nCols;

No height field in the JSON. There is no nRows or nHeight key. Height is always inferred from aSocketAdds.Count / nCols. The socket array entries themselves are loot-table names like "TILItemAdds" — their count is what determines footprint; their values govern what tiles the item may be placed on.

Canonical examples from data/items/items.json

How visual footprint works

For a static (non-animated, non-sprite-sheet) item, the game computes a scale vector from the source PNG dimensions at load time. The relevant lines are at Item.cs:285-286:

this.vScale.x = (float)Mathf.Max(MathUtils.RoundToInt(
    1f * (float)this.rend.sharedMaterial.GetTexture("_MainTex").width  / 16f), 1);
this.vScale.y = (float)Mathf.Max(MathUtils.RoundToInt(
    1f * (float)this.rend.sharedMaterial.GetTexture("_MainTex").height / 16f), 1);

// Item.cs lines ~282-289 (static-sprite path inside Item.SetData)
else
{
    this.rend.sharedMaterial = DataHandler.GetMaterial(this.rend,
        this.strImgOverride, this.strImgNormOverride,
        this.strImgDamagedOverride, this.strDmgColorOverride);
    this.vScale.x = (float)Mathf.Max(MathUtils.RoundToInt(
        1f * (float)this.rend.sharedMaterial.GetTexture("_MainTex").width  / 16f), 1);
    this.vScale.y = (float)Mathf.Max(MathUtils.RoundToInt(
        1f * (float)this.rend.sharedMaterial.GetTexture("_MainTex").height / 16f), 1);
}
this.rend.sharedMaterial.SetVector("_Aspect", new Vector4(
    (float)this.nWidthInTiles, (float)this.nHeightInTiles,
    (float)this.rend.sharedMaterial.GetTexture("_MainTex").width,
    (float)this.rend.sharedMaterial.GetTexture("_MainTex").height));

The tile size constant is 16 pixels. The game divides raw PNG width and height by 16 to get the number of tiles the sprite occupies visually. There is no config variable for this — it is a hard-coded integer literal throughout the rendering code. (The same constant appears in the inventory renderer at GUIInventoryItem.cs:173,177 and in the GetPos offset math at CondOwner.cs:7360.)

So for a sprite to display as an N×M tile item:

PNG width  = N * 16 px
PNG height = M * 16 px

A 1×1 item needs a 16×16 PNG. A 2×1 item needs a 32×16 PNG. A 1×2 item needs a 16×32 PNG.

The two ways sprite size goes wrong

Symptom 1: PNG too big

Your PNG is, say, 64×64 pixels. The game divides by 16 and gets a vScale of (4, 4) — a 4×4-tile visual footprint. But your item's aSocketAdds has one entry (nWidthInTiles = 1, nHeightInTiles = 1), so the _Aspect vector says 1×1. The shader stretches a 64×64 texture across a 1-tile cell, and the item renders giant.

Fix: Resize the PNG so its pixel dimensions match the intended logical footprint:

target PNG width  = nCols                         * 16 px
target PNG height = (aSocketAdds.Count / nCols)   * 16 px

For a standard single-slot item: 16×16 px. For a 2-wide weapon: 32×16 px.

Symptom 2: Logical footprint wrong

The opposite: your PNG is the right size but you forgot to set nCols or aSocketAdds to match the intended footprint. The item visually occupies 1 tile but its socket array says it's 2×1, so it won't fit into 1-tile-wide inventory slots.

Fix: Audit nCols and aSocketAdds.Count together. The relationship must be:

nCols == intended width in tiles
aSocketAdds.Count == nCols * (intended height in tiles)

If you want a 2-wide, 1-tall item: set "nCols": 2 and supply exactly 2 entries in aSocketAdds.

Installables — two items, two sprites

Wall-mounted fixtures — capacitors, pipes, light fixtures, reactor modules — exist in two separate condowners/ entries with two separate items/ item definitions. Neither entry is the "primary" one. They are genuinely different objects that the install/uninstall system swaps between.

• The installed form is the wall-mounted object. Its aSocketAdds entries use fixture-type sockets ("TILFixtureAdds", "TILFixtureAdds", etc.) and its starting conditions include IsInstalled=1.0x1 and IsHiddenInv=1.0x1. IsHiddenInv prevents it from showing as a loose item in inventory UIs. This entry drives the world sprite — the form you see bolted to the wall.
• The loose form is the same physical object once uninstalled. Its aSocketAdds entries use floor-placement sockets ("TILItemAdds"), it can be picked up and carried, and its sprite is typically a compact "folded" or side-on representation sized to fit comfortably in an inventory slot. The loose form has no IsInstalled or IsHiddenInv condition.

The install/uninstall transition is mediated by an entry in data/installables/installables.json (deserialized as JsonInstallable). An installable record ties the two forms together: strActionCO names the loose CondOwner, aLootCOs names the installed CondOwner that replaces it, and strStartInstall names the installed item definition used to position the installed form on the ship grid.

Neither form uses a special sprite field — each uses the standard strImg on its own JsonItemDef. The sprite scaling rules (nCols × 16 px wide, aSocketAdds.Count / nCols × 16 px tall) apply independently to each form.

Worked example: fusion reactor capacitor

The fusion reactor capacitor is the clearest example in the base game data. Its two entries are in data/items/items.json and data/condowners/condowners_reactor.json:

Installed form — ItmCapacitor01

{
  "strName"       : "ItmCapacitor01",
  "strImg"        : "ItmCapacitor01",
  "strImgNorm"    : "ItmCapacitor01n",
  "nCols"         : 2,
  "aSocketAdds"   : [
    "TILFixtureAdds", "TILFixtureAdds",
    "TILFixtureAdds", "TILFixtureAdds",
    "TILFixtureAdds", "Blank",
    "TILFixtureAdds", "Blank",
    "TILFusionReactorPartsFixtureAdds", "Blank"
  ]
}

• nCols = 2, aSocketAdds.Count = 10 → logical footprint 2 wide × 5 tall, so the installed-form PNG must be 32 × 80 px.
• Socket type: TILFixtureAdds — fixture-mount tiles only. This form cannot be dragged into a cargo bay; it can only be placed on a ship wall by the install interaction.

The matching condowners_reactor.json entry starts with IsInstalled=1.0x1 and IsHiddenInv=1.0x1, which keep it invisible to the inventory UI while mounted.

Loose form — ItmCapacitor01Loose

{
  "strName"       : "ItmCapacitor01Loose",
  "strImg"        : "ItmCapacitor01Loose",
  "strImgNorm"    : "ItmCapacitor01Loosen",
  "nCols"         : 2,
  "aSocketAdds"   : [
    "TILItemAdds", "TILItemAdds",
    "TILItemAdds", "TILItemAdds",
    "TILItemAdds", "TILItemAdds"
  ]
}

• nCols = 2, aSocketAdds.Count = 6 → logical footprint 2 wide × 3 tall, so the loose-form PNG must be 32 × 48 px.
• Socket type: TILItemAdds — floor tiles. This form can be set down, picked up, and moved freely.

The installable record connecting them is in data/installables/installables.json:

{ "strName": "Capacitor01Install",
  "strActionCO": "ItmCapacitor01Loose",
  "aLootCOs": [ "ItmCapacitor01" ],
  "strStartInstall": "ItmCapacitor01",
  "strJobType": "install", ... }

{ "strName": "Capacitor01Uninstall",
  "strActionCO": "ItmCapacitor01",
  "aLootCOs": [ "ItmCapacitor01Loose" ],
  "strJobType": "uninstall", ... }

What to do when modding an installable

1. Create two items/ entries and two condowners/ entries: one installed form (fixture sockets, IsInstalled, IsHiddenInv), one loose form (floor sockets, pickup/drop interactions).
2. Create two installables/ entries: one strJobType: "install" and one strJobType: "uninstall", linking the loose CondOwner to the installed CondOwner and back.
3. Size each PNG independently. The installed form's PNG should match its wall-mount footprint (nCols × 16 wide, socket-count-rows × 16 tall); the loose form's PNG should match its carry/inventory footprint, which is typically smaller.
4. Both entries can have their own strImgNorm. The loose form often uses the same normal map as the installed form (as the capacitor does: both reference ItmCapacitor01n / ItmCapacitor01Loosen), but they can differ.

Inventory icon

The inventory icon is not a separate sprite field. The inventory grid renders the same strImg PNG that the floor view uses, loaded via item.ImgOverride (which defaults to jid.strImg). The rendered size in the inventory grid is determined at GUIInventoryItem.cs:154-182:

1. Start from the raw PNG width/height.
2. If the item's CondOwner definition (in data/condowners/condowners.json) has a non-zero inventoryWidth or inventoryHeight, override the pixel count: num = inventoryWidth * 16 (same 16-px constant). Then pass those dimensions to the _Aspect shader vector.
3. If both inventoryWidth and inventoryHeight are zero or absent (the common case — no base-game item in the current data uses these fields), the inventory falls back to the raw texture dimensions.

The grid slot size itself comes from GUIInventoryItem.GetWidthHeightForCO (GUIInventoryItem.cs:18-37): it starts with item.nWidthInTiles / nHeightInTiles, then overrides with inventoryWidth / inventoryHeight from the CondOwner def if set.

// GUIInventoryItem.cs:154-157 (inside DrawItem)
// Inventory renders from item.ImgOverride, which is jid.strImg
// No strImgIcon or strImgInventory field exists on JsonItemDef.
texture = DataHandler.LoadPNG(item.ImgOverride + ".png", false, false);
material.SetTexture("_MainTex", texture);

strImg

On the items/ entry (JsonItemDef). Path to the PNG without extension. Used for both the floor render and the inventory icon. Example: "strImg": "ItmDrinkFlask01" loads ItmDrinkFlask01.png.

inventoryWidth / inventoryHeight

On the condowners/ entry (JsonCondOwner). Optional override for the inventory grid slot size, in tiles. Rarely needed — only set these if you want the inventory representation to differ from what the PNG dimensions imply. Zero (or absent) means "use the PNG dimensions."

strImgNorm — the normal map

strImgNorm is the field on JsonItemDef (in your items/ entry) that points to the normal-map texture. The game passes it to DataHandler.GetMaterial alongside strImg, and the shader reads it as the _BumpMap texture to compute per-pixel lighting direction. Without it, the item renders with flat lighting.

// DataHandler.cs:3461-3468 (inside DataHandler.GetMaterial)
material.SetTexture("_MainTex", DataHandler.LoadPNG(strImg + ".png", false, false));
material.mainTextureScale  = new Vector2(1f, 1f);
material.mainTextureOffset = default(Vector2);
if (strImgNorm != "blank")
{
    material.SetTexture("_BumpMap", DataHandler.LoadPNG(strImgNorm + ".png", true, false));
    material.SetTextureScale("_BumpMap",  new Vector2(1f, 1f));
    material.SetTextureOffset("_BumpMap", default(Vector2));
}

The field is optional. If you omit strImgNorm or set it to "blank", the item will still render; it just won't respond to the ship's dynamic lighting the way vanilla items do. For quick prototyping, you can skip it entirely and add it later.

// Item.cs:447-449 (inside Item.SetUpInventoryMaterial)
if (this.strImgNormOverride != "blank" && this.strImgNormOverride != "" && this.strImgNormOverride != null)
{
    // BUG: loads strImgOverride (the diffuse texture) instead of strImgNormOverride
    material.SetTexture("_BumpMap", DataHandler.LoadPNG(this.strImgOverride + ".png", false, false));
}

// Compare: DataHandler.GetMaterial (world render, correct):
// material.SetTexture("_BumpMap", DataHandler.LoadPNG(strImgNorm + ".png", true, false));

When you are ready to add a normal map, the standard workflow (used for all vanilla assets) is:

1. Open your strImg PNG in GIMP.
2. Go to Filters → Generic → Normal Map.
3. Adjust depth to taste (vanilla items typically use modest depth values so the lighting reads subtly). Export as a separate PNG.
4. Set "strImgNorm": "<your-normal-map-filename-without-extension>" in the item def.

Off-center rendering and mapPoints

The floor render positions the item's GameObject at the world coordinates (fX, fY) from the ship JSON, then sets localScale to (vScale.x, vScale.y, 1) (Item.cs:591-593). The origin of a Unity sprite is the center of its renderer bounds — so a 16×16 sprite on a 1×1-tile cell is centered on the tile grid point. A 32×16 sprite is centered on the midpoint between its two tile columns.

What causes off-center rendering. If your PNG is not an integer multiple of 16 px in each dimension, the MathUtils.RoundToInt(... / 16f) call rounds to the nearest integer tile count. A 20-px-wide sprite rounds to 1 tile of visual scale (20/16 = 1.25, rounds to 1), so the extra 4 px get cropped. A 24-px sprite rounds to 2 tiles (24/16 = 1.5, rounds to 2), so it renders at 2-tile width with most pixels unused — both cases look "off" in different ways. Keep PNG dimensions to exact multiples of 16.

mapPoints — named interaction offsets. The mapPoints field (on the JsonItemDef entry, and also on JsonCondOwner entries) defines named pixel offsets from the item's world position. Each entry is a comma-separated string "name,x,y" where x and y are in pixels relative to the item's center, divided by 16 to convert to world units (CondOwner.cs:7360). For example, "use,24,0" places the "use" interaction point 24 px (1.5 tiles) to the right of center.

// CondOwner.cs:7357-7363 (inside CondOwner.GetPos)
// mapPoints values are used ONLY to offset interaction points.
// The sprite transform is set independently in Item.ResetTransforms.
foreach (string entry in this.mapPoints)
{
    string[] parts = entry.Split(',');
    if (parts[0] == strPointName)
        return new Vector2(float.Parse(parts[1]) / 16f, float.Parse(parts[2]) / 16f);
}

mapPoints does not shift the sprite itself — it only affects where crew stand when interacting with the item, and where things like power cables connect. The sprite's visual anchor is always at the sprite center; mapPoints cannot be used to "nudge" the rendered image relative to the tile grid.

Confidence — what was verified vs. inferred

Summary: 9 verified, 0 inferred. All nine claims are grounded in specific lines of decompiled C# and/or confirmed against live data entries.