User:Greys

From Kerbal Space Program Wiki
Revision as of 05:19, 1 September 2013 by Greys (talk | contribs) (Asset Parameters)
Jump to: navigation, search


This document is presented as a tutorial when, as suggested by the page title, it should be a reference.

At first glance, the configuration file for an addon is a pretty confusing and infuriating thing. This tutorial will walk through the individual parts of the configuration file and hopefully give you an idea what everything does. As we go along, we'll build up a dummy part file that will behave exactly like a real one, only lacking models, sounds, and textures.


Part file creation


Okay, now that's out the way we can start looking into Part files, and how they work. Although it looks pretty confusing at first glance, it's actually a pretty simple ordeal to create one. To start, we're going to actually need an empty file in the right location.

  • Fire up notepad
  • Save it as "part.cfg" in the directory of your addon
Ø File name does not have to be "part" anymore
    • Usually "../KerbalSpaceProgramDirectory/Parts/yourAddon"
Ø /KSP/Parts/ is considered a legacy mode folder, parts that use it will not have the config options added in 0.20 available to them


There, you now have an empty file waiting for juicy bits of configuration to be stuck into it. So let's keep going.


General Parameters:


Now, let's look at the next section of the file - the general parameters.

// --- general parameters ---

This section comes straight under your title, and provides a few general things that apply to all parts. Here's a list of what goes under General Parameters:

Pretty easy, huh? No? Still a bit muddled? Okay, explanation time.

name
This is just that, a name. It can be anything, but notice that it's NOT commented out. This is what KSP will refer to the part as internally. It's good form to keep it all one word. Don't worry, you won't see it called this in game, so it can honestly be anything. Must be unique and cannot contain the underscore.
Ø or spaces
module
Now this is slightly more difficult. Each part can be one of several different types of parts, defined by what comes after module. What type the part is defines how it works - for example, a solid rocket booster behaves differently from a liquid rocket motor. See Valid Part Modules for values you can use here.
author
Put your name here, you're the author!

So let's get on with our dummy file.


There we go, a liquid engine type part, by proud author YourName.

Modules


So what part types can you have?

Part Name Description
ControlSurface Movable wing-like surface. Can act as a rudder, aileron, elevator, canard or other aerodynamic control surface - function depends on placement on a ship.
Winglet A lift producing part. Not movable.
StrutConnector Used for making struts (the space ducttape kind)
FuelLine Allows for transfer of fuel.
HLandingLeg A moving landing leg, using .cfg parameters to move.
Part This module should be used for all parts except for a few specific instances where the module has not yet been replaced with a partModule


There is nothing special about module Part.

Part Modules



Asset Parameters


This section defines the assets of our module - it provides us with links to our model and to our texture file, as well as giving us some extra settings to play around with.


Lets go through them.

mesh
Ø mesh is depreciated and does not need to be used if MODEL{} is used, or only one .mu is present in the folder with the .cfg
scale
Ø If scale is not 1, you have failed to properly configure your modeller and should correct this before moving forwards, as it does significantly complicate things
texture
Ø texture is depreciated
Ø The name of the texture to be used is included in the .mu file, and does not need to be explicitly stated unless it differs, and you would not use this variable to do so
specPower
The specular reflectivity of your part. It's best to leave it as it is.
rimFalloff
This defines the strength of the highlight effect in game. Higher values lead to a more pronounced effect near the edges.
alphaCutoff
This number defines the threshold for transparency on the part's texture. If your texture has an alpha channel (transparency), you can adjust this number to make sure your part is transparent or opaque where it should be. A value of 0 means nothing in the texture is considered to be transparent. A value of 1 means a completely transparent part.
rescaleFactor
Ø rescale factor should be explicitly set to eliminate complications

There, that's everything under asset parameters covered. Let's continue building our dummy part file.


Onwards!

Node Definitions


Another fairly easy section, this defines where we attach our part to other parts. You can have as many as you want, for example, tricouplers have four, three bottom and one top, while most parts simply have two, and a few parts have only one.

node_stack_bottom = x, y, z, angx, angy, angz, size
node_stack_top = x, y, z, angx, angy, angz, size
node_attach = x, y, z, angx, angy, angz, size

There's three example nodes. There are three different kinds, but only two are useful to us at the moment. We have node_stack and node_attach. Node stack is for defining where the part stacks vertically together with other parts, and node attach is used for defining where on the surface of your part other parts attach - so horizontal attachment.

All node attachment values are given with respect to an object's origin, and their values correspond to a model's units and scaling factors. A node_stack_bottom with x, y, and z values of (2.5, 5.0, 3.0) will have an attachment node 2.5 units to the right, 5.0 units up, and 3.0 units forward. The next three values refer to the orientation that a particular node will accept other attachments, on a scale of -1.0 to 1.0. These represent the vector that a part will orient itself on when attaching to the node. For example, a fuel tank with a node_stack_bottom will have angx, angy, and angz values of (0.0, -1.0, 0.0). This represents a vector downward relative to the part model, in the negative y direction. A value of (0.0, -1.0, 1.0) would represent a diagonal vector downward and forward, while a value of (1.0, 1.0, 1.0) would represent a vector to the right, up, and forward.

Generally, most parts will have angx, angy, and angz values of either (0.0, -1.0, 0.0) for a node_stack_bottom and (0.0, 1.0, 0.0) for a node_stack_top.

The last value indication the visual size of an attachment node. Values may be either 0 (small half-meter node), 1 (normal), or 2 (large). This parameter is optional and will default to 1 if nothing is specified. Keep in mind, naming conventions (_stack_bottom, _stack_top) for nodes only apply to node_attach; they are only helpful in identifying a node's position.


FX definitions:

More definitions! But this time, you're positioning the flame coming out the back of the rocket.

fx_exhaustFlame_yellow = x, y, z, angx, angy, angz, active
fx_exhaustLight_yellow = x, y, z, angx, angy, angz, active
fx_smokeTrail_medium = x, y, z, angx, angy, angz, active

Okay, looks pretty similar to node_definitions, right?

You'll notice, just like node definitions, there are separate parts to each effect. You have fx_exhaustFlame, fx_exhaustLight, and fx_smokeTrail.

There are exactly what they sound like, the flame, the light, and the smoke trail.

There are variations on flame color, blue is also an option. To get a blue flame, you would use fx_exhaustFlame_blue. You would do the same for the exhaustLight.

The 'active' switch on the end is used to define when this effect will be visible. See the FX Groups listing to know which effect groups are available, and when they are used. It's also possible to assign an effect to more than just one FX Group. If for instance, you want a smoke effect to be visible both when the part activates and also when it deactivates itself, you can do this:

fx_gasBurst_white = x, y ,z, angx, angy, angz, activate, deactivate

This is particularly useful if you're defining a lot of effects, like the gas discharges on an RCS module.

Feel like you're getting the hang of this now? Let's keep building the dummy part file, and add in a blue flame and light, but leave out the smoke trail.


Editor Parameters:

Aha! We're back to parameters! These set of parameters let us decide how our part is displayed in the rocket editor. This section has the following:

// --- editor parameters ---
cost = 450
:Ø Cost must be an integer, no commas or periods; and it might need to be greater than 0. non-integer values will cause this part and every scheduled to be loaded after it to not be loaded.
category = Propulsion
subcategory = 0
title = 
manufacturer =
description = 
cost
This hasn't really been implemented yet, but when it is it sets the cost for spaceship parts. You can set this to anything for now, it's entirely up to you.
category
There are seven categories:
Category Description
Pods Command pods and cockpits go here
Propulsion Engines, Fuel Tanks, RCS Tanks, etc.
Control SAS modules, RCS Thrusters, etc.
Structural Struts, decouplers, adapters, etc.
Aero Wings, Control Surfaces and nose cones.
Utility Parachutes, Escape towers, heat shields, lights, landing gear/legs, ladders, batteries, solar panels, generators, etc.
Science Sensors, Antennae, Satellite Dishes, etc.


subcategory
No use yet. Set it to 0
title
What do you want your part to be called in the rocket editor?
manufacturer
Who built your part?
description
Describe your part here. (Do not use linebreaks. KSP breaks lines automatically in the part's tooltip. A linebreak will cause your description to appear truncated)

And that's that. Updating the dummy cfg file now:


Attachment rules:

This defines how your part attaches to other parts.

  • // attachment rules: stack, srfAttach, allowStack, allowSrfAttach, allowCollision
  • attachRules = 1,1,1,1,1

The rules correspond to the numbers below - 1 is allow, 0 is prevent. The tags are:

stack - Can your part be stacked on others?

SrfAttach - Can your part be placed onto a surface?

allowStack - Will you allow other parts to be stacked on your part?

allowSrfAttach Can other parts be placed on the surface of yours?

allowCollision - A special one: Can your part be placed if part of it is intersecting another part?


Note that you can also force parts attached to this part to attach in a specific symmetry.

  • // symmetry rules: 0=1x, 1=2x, 2=3x, 3=4x and so on...
  • stackSymmetry = 3


Easy enough, right? Adding to dummy file and continuing.


Standard Part Parameters:


This defines how your part performs in the air and its limits. Note that not all of these parameters need to be defined. If they're left out of the cfg file, KSP will use a default value for them.

  • mass =
  • dragModelType = default
  • maximum_drag =
  • minimum_drag =
  • angularDrag =
  • crashTolerance =
  • breakingForce =
  • breakingTorque =
  • maxTemp =
  • stageOffset =
  • childStageOffset =
  • fuelCrossFeed =
  • NoCrossFeedNodeKey =

mass - How much does your part weigh? (Or, for parts that also specify a dryMass parameter, how much does it weigh when full?)

dragModelType - Leave this as default.

maximum_drag - What's the maximum amount of drag on your part? (Usually under 1.) Generally drag when part's direction of travel is along its y-axis.

minimum_drag - The minimum amount of drag your part will encounter. (Usually under 1 and lower than maximum_drag) (this value is unused if dragModelType is set to default) Generally drag when the part's direction of travel is perpendicular to its y-axis.

angularDrag - how much angular drag is there/resistance to turning? (Also usually under 1.)

crashTolerance - How good is your part at surviving crashes? The higher the number the more durable. Numbers are approximately maximum impact speed in m/s.

breakingForce - The amount of linear force at which the joint will fail. This variable does not impact the stiffness of the joint.

breakingTorque - The amount of rotational force at which the joint will fail. This variable does not impact the stiffness of the joint.

maxTemp - The maximum temperature your part can experience before exploding.

stageOffset and childStageOffset - Can be 0, 1, etc. defines whether this part will create a new stage before or after itself, or both (as do decouplers). This only applies for the automatically generated staging sequence. These replace stageBefore and stageAfter.

fuelCrossFeed - Will the part crossfeed fuel between parts attached to it?

NoCrossFeedNodeKey - if set to bottom will keep fuel from flowing FROM bottom nodes (avoiding some stack imbalances and partially mitigating the 0.15 bug of engines generating fuel). Used with parts with multiple bottom nodes, such as the TVR-1180C Mk1 Stack Tri-Coupler.

Specific Part Parameters:


We're almost finished, a complete part is almost at our hands and you should know almost everything you need to create a part.cfg file. However, remember back when we were setting types? Well each type has an individual set of specific part parameters that change depending on what type of part it is.

You cannot mix and match parameters from different module types - it doesn't work.

These specific parameters are actually public variables defined in the Part classes themselves. The standard parameters are declared in the Part base class, and the specific ones in each Part extension (i.e., Modules)

Time to go through and see what special parameters each module can have.

Winglets

  • dragCoeff =
  • deflectionLiftCoeff =

dragCoeff - The drag co-efficiency of the wings.

deflectionLiftCoeff - How much lift the wings generate.

Control Surfaces

  • dragCoeff =
  • deflectionLiftCoeff =
  • ctrlSurfaceRange =
  • ctrlSurfaceArea =

ctrlSurfaceRange - How far off centre the control surface (rudder / aileron etc) can move under control

ctrlSurfaceArea - The effective surface area of the control surface - the bigger the surface, the bigger the surface area must be set to