Stats

Stats (short for statistics) are the additional, detailed information about parts, projectiles that have ties to them, and other things like buffs.

To see the stats for some part in-game, move your mouse over the part you're interested in and press and hold the Alt. Alternatively, you can do the same on the part's icon in Build Mode (a.k.a. the "Ship Editor").

That view is called the "Detailed description" ^{[fact check needed]} but we will call it alt-description in this page, for short.

Detailed description of laser blaster

On the right is an example of the alt-description for the Laser Blaster. Come back to it as many times as needed to see exactly what we're talking about.

In the .rules files, the values for Stats can be written easily as static values, but that's a pretty rare way of doing it. They're usually calculated by the game using paths to reference values, and math formulas in many cases.

Examples

• missile_launcher stats for "stored HE missiles", "stored EMP", etc., are static values manually entered by the developer. They must be manually updated with every change. In this case there isn't a value to reference, it's just the number of BulletEmitter components in the code.
• The "Shield Pen. Resist" stat in shield_gen_small.rules directly references the stat : ShieldPenResist = &~/Part/Components/ArcShield/PenetrationResistance/0.

The good and the bad

When using paths to reference the values and calculate stats like "Damage per second" (referencing Damage & Interval between shots), these calculations have a major perk and 2 major drawbacks :

• If your formulas are correct, any change to the actual value will update the displayed stat automatically.
• If they are not correct, the displayed results will simply be wrong,
• If a path isn't correct (sometimes because you moved a block of code) the game crashes during loading.

Note that this is the method used in the overwhelming majority of game stats.

Tip

This is also why when a new modder adds a part in their mod, it's much easier to just comment out the entire Stats block, especially for early testing.
You can then go back to fix it when things have settled down.

Stats

These are each individual statistic present in the alt-description.

E.g: Power Capacity: 4 , Size: 1x3 meters , or Range: 260 meters in the alt-description for Laser Blaster (small).

Example : Range

Let's take a closer look at the Range stat.

1. Stat in the part

First, the part fetches the value using a path reference, in the Stats{} block at the very bottom of the part's .rules file :

Range = &~/Part/Components/BulletEmitter/Bullet/Range

Info

These references can target anywhere.
A common example is targeting stats in the associated projectile's file, like here.

The /Bullet/ field in this path looks like this (still in laser_blaster_small.rules ) :

Bullet = &<./Data/shots/laser_bolt_small/laser_bolt_small.rules>

As we can see, this sends the game to the .rules file for the associated projectile, laser_bolt_small.

The Range is defined right there at the very top, and that's the end of the path.

Now, how does the game display it and make sure it's in the right language?

2. Part Stats

In the part_stats.rules file located in Data/gui/game/parts, within the all-encompassing PartStats[], this block can be found :

{
	ID = Range
	FormatKey = "Stats/RangeFmt"
}

It links the Range stat in the part to its appropriate formatting (hence the "Fmt") in the languages files.

3. Formatting in the language file

This is what it looks like in the en.rules :

RangeFmt = "<white>Range:</white> <good>{0:0}</good> <gray>meters</gray>"

The <> tags work like HTML tags and make the the text nice and colored in-game. By default, anything in the middle of <good> </good> looks green.

More importantly, this line contains what the player will actually see, within the " ".

The {0:0} means that the value provided in step 1 will be placed there.

Stat categories

StatCategories are the "titles" in the alt-description, such as "Laser Bolt", which group a bunch of stats together, such as all the stats of that projectile.

StatCategories are automatically displayed in bold font and separated from any stats above by an empty line, which make them stand out and cleanly organize your alt-description.

Here is that entire section in the base game, found deep within en.rules :

StatCategories
{
	LaserBoltSmall = "Laser Bolt"
	LaserBoltLarge = "Heavy Laser Bolt"
	DisruptorBolt = "Disruptor Bolt"
	IonBeam = "Ion Beam"
	PDShot = "Point Defense Round"
	BulletMed = "Standard Cannon Round"
	BulletLarge = "Large Cannon Round"
	BulletRailgun = "Railgun Round"
	BulletDeck = "Deck Cannon Round"
	Flak = "Flak"
	MissileHE = "High-Explosive Missile"
	MissileEMP = "Electromagnetic Pulse Missile"
	MissileNuke = "Tactical Nuclear Missile"
	Mine = "Mine"
	MineShrapnel = "Shrapnel"
	BoostOff = "Boost: Off"
	BoostOn = "Boost: On"
	TractorBeam = "Tractor Beam"
	RailgunBuff = "Railgun Buff"
	MiningBeam = "Mining Beam"
	BulletChaingun = "Chaingun Round"
	CollectorBeam = "Collector Beam (x4)"
}

How to use in your mod

Stats

If you can manage it, it's best to include any stats relevant to parts you add, even if they are just variants of existing parts. This will allow players to know what they're dealing with and try to optimize their design and strategy for the energy costs, etc.

To add any Stats that won't crash, follow these 3 steps :

1. Add the stat to your part

If you copied the part from a base game part, chances are everything you need is already there at the bottom of your part, in the Stats{} block, and you just need to fix the paths and you're done. Skip steps 2 and 3.

If not, add any Stat(s) you want to display like this :

• If it's a static value : MyNewStat = 2 or whatever number it should be ;

• If it's just a reference : MyNewStat = &~/ReferenceForThatStat/FieldInReferenceIfAny, making sure your path is correct ;
  • Note : for angles in degrees it's MyNewStat = deg(&~/ReferenceForThatStat/FieldInReferenceIfAny) instead ;
• If it's calculus using references : MyNewStat = (&~/FirstReferenceForThatStat) * (&~/SecondReferenceForThatStat) or whatever formula should be used.

2. Add to part_stats.rules

If it's a brand new Stat that doesn't exist anywhere else in the game (Ctrl+F in part_stats.rules to be sure), it needs to be added to part_stats.rules to establish the link between the Stat and language files.

This is done in your mod.rules file with an Add or AddMany action like so :

{
	Action = AddMany
	AddTo = "<gui/game/parts/part_stats.rules>/PartStats"
	ManyToAdd
	[
		{
			ID = MyNewStat
			FormatKey = "Stats/MyNewStatFmt"
		}
	]
}

3. Add the formatting to en.rules

Lastly, for the game to know how exactly it's supposed to display that, add (embed) a block of code like this to your en.rules  :

Stats
{
	MyNewStatFmt = "<white>My New Stat:</white> <good>{0:0}</good><gray>UnitOfMyNewStat</gray>"
}

As seen previously, the <> tags work like HTML tags and allow you to color the text the same way it is colored in the base game (else it looks odd, but you might want that). It should even work in colorblind modes.

Repeat as needed for your other language files (if any). You're done with Stats.

Stat categories

Details about StatCategories are higher in this page, if you missed it.

If you copied a base game weapon properly and only changed some values around like the damage of a projectile or the HP of the part, there should be nothing more to do.

Otherwise, create a StatsByCategory block at the bottom of the .rules of the part that should display it, and add the block of Stats you want within it (or a reference to them).

If it's a block that doesn't exist in the base game, that block must be given a unique NameKey. Then add it to your en.rules in a block of code like this :

StatCategories
{
	StatCategoryNameForMyFirstProjectile = "My First Projectile"
	StatCategoryNameForMy2ndProjectile = "My 2nd Projectile"
}

If you are adding more projectiles/buffs/modes etc, just copy paste the lines as needed, still within the {}, and edit them.

Repeat as needed for your other language files (if any). That should be all.

Example result

Example mods

"Missile Launcher variant : Crippler" by Dj0z : new stat category "MissileCrippler" and new stat "BulletLifetime".

"Jani's Shipyard" by JaniTNT : all manner of stats.