Skip to content

Writing page definition files

Eugene Medvedev edited this page Dec 10, 2013 · 39 revisions

Page definition files are normal text files in UTF-8 encoding, lines are separated by normal line break characters. Both Windows and Linux/Mac line breaks work - just don't mix them in one file. Extension can be anything, but .txt is recommended. (KSP may take offence if it's .cfg) The real power of screen definitions comes from the [String.Format][1] C# function which is applied to them: various pieces of data can be inserted anywhere into the text. For a quick reference of how String.Format works and some examples you can see this handy blog post. An example: [1]: http://msdn.microsoft.com/en-us/library/system.string.format(v=vs.90).aspx

Altitude is {0:##0.00} $&$ ALTITUDE

The special sequence of symbols "

Unable to render expression.

$&$
" separates the text to be printed from a space-separated list of variables to be inserted into the format specifiers on the line. It might not be very obvious, but the first character of the {} format specifier is the index of the variable in the list, starting with 0. There are a lot of tricks you can do by abusing the capability of String.Format to select between different formats (and by extension, select what to print at all) depending on whether a certain variable is positive, negative or zero. For this reason, special variables that return -1 or 1 in specific situations are included.

While debugging your page definition, it helps to know that the plugin reloads page definitions from disk, (the ones stored in files, at least) every time it is instantiated, which is every time the vessel is loaded -- which happens if you go back to the space center and return, or even simply switch to an out of range vessel and back.

Colortags

The font can be tinted on the fly into any RGBA color. To do this, insert a tag in the form of [#rrggbbaa] where rr,gg,bb and aa are color components presented in hexadecimal just like in HTML colors. The tag remains active until the end of line, to switch back just insert another one - [#ffffffff] would be the default.. For a more detailed introduction into HTML colors consult a HTML color chart -- remember that it does not generate alpha as HTML only uses it occasionally, you need two extra symbols at the end which are the alpha -- "FF" is completely opaque, "00" is completely transparent.

Beware that if your font is natively bright white in the font bitmap, brighter colors might not result in a noticeable color change at all. For best results, make your font bitmap a 50% grey if you wish to use tinting throughout.

Extra formatting options

The standard String.Format is extended with several extra format options to handle KSP-specific formatting needs:

SI prefixes

That is, kilo-meters, mega-meters, giga-meters, etc, which is very handy for altitudes and speeds.

{0:SIP_05.2}m/s $&$ VARIABLE

This will format a value with SI prefixes, i.e. this way 65000m can become 65km and your values can squeeze into smaller fields of fixed width.

Assuming VARIABLE is a number, it will be formatted to fit into 5 characters, with no more than .2 digits after the decimal point. Since it includes a _ marker, a space will be inserted between the SI prefix and the number, and since the number of characters starts with a 0, it will be padded to the right with zeroes. 0, _ and the post-decimal point specifier are optional -- if there's no zero, it will be padded to the right with spaces, if there's no decimal point, the plugin will decide how many digits after decimal are permissible.

Degrees-minutes-seconds

This will format an angle into degrees, minutes and seconds, inserting appropriate characters denoting those if required:

  • DMS -- format prefix
  • N,S,E,W -- Any of these characters will be replaced by the correct character depending on the sign of the value. N and S will mean latitude is used, E and W will mean longitude is used.
  • d -- degrees, no padding.
  • dd -- degrees, zero padding.
  • m -- minutes, no padding
  • mm -- minutes, zero padding.
  • s -- seconds, no padding.
  • ss - seconds, zero padding.
    • -- replaced by the appropriate degree-minute-second symbol, if encountered immediately after d, m or s.

All other characters will be passed unaltered. Example usage:

{0:DMSd+ mm+ ss+ N} -- will format a latitude value exactly 
                       like the old LATITUDE_DMS variable would.
{0:DMSd+ mm+ ss+ E} -- will format a longitude value exactly
                       like the old LONGITUDE_DMS variable would.

Time formatting

Kerbals have some special needs regarding the display of time -- for example, it makes no sense whatsoever to speak of Kerbal months. To fit those special needs, the KDT formatter was introduced. Notice that all of this refers to a "year" that is 365 days long, a "day" that is 24 hours long, etc -- actual orbital period of Kerbin is not used for Kerbal calendar anywhere in the game.

  • KDT -- format prefix
    • -- Replaced by a plus sign if the time span is positive and a minus sign if the time span is negative.
    • -- Replaced by a space if the time span is positive, and a minus sign if the time span is negative.
  • y -- Number of years.
  • d -- Number of days.
  • D -- Number of whole days, i.e. assuming that there will be no years in the output.
  • h -- Number of hours.
  • H -- Number of whole hours, i.e. assuming that there will be no days or years in the output.
  • m -- Number of minutes.
  • M -- Number of whole minutes, i.e. assuming that there will be no hours or above in the output.
  • s -- Number of seconds.
  • S -- Number of whole seconds, i.e. assuming that we're only showing seconds.
  • f -- Fractional seconds. Repeating this character will produce further sub-second resolution.

All other characters are passed unchanged. Using one specifier character will insert the entire number, i.e. Repeating the specifier character more than once means that the resulting number will be padded with zeroes to produce a string of that many characters. Examples:

{0:KDTyy:ddd:hh:mm:ss.f} -- Most time values were previously returned like this: no sign, 
                            two digit year, three digit day, two digit hour, two digit minute,
                            two digits second, one digit fractional second.
{0:KDTy:d:h:m:s.f} -- Will show the same without padding values with zeroes.

Variables

For a full list of variables you can use, see Defined variables.