Difference between revisions of "Part Modelling Guidelines"

Latest revision as of 08:33, 8 April 2024

Large portions of this page are originally incorrect or so outdated that they are no longer useable. The folder structure has been updated (see below for notes), but KSP has switched to a new 3D-Format (version 3 .mu).

Modelling a part for KSP is like making any model for a game. It's required, however, to consider a few details, which make the part work in the game. Once modelled, the model must be exported to a format KSP can read. Currently, KSP only supports loading of 3D models in .mu format.

Config

Once the model is exported, it's necessary to configure the new part so that the game knows how it should work. Are you making a new Solid Rocket Booster or a Command Capsule? How powerful (or weak) should that engine be (if it is, in fact, an engine)? Defining a generic implementation for all imaginable types of parts would be quite an impossible task. Likewise, programming each part independently would also be rather unpleasant. For this reason, KSP uses configuration files (CFG files) that define how a part must work, and the parameters needed to make each part unique.

The File System

This section has been updated, but it still require clarification

Before starting to build a part, it's important to understand how your files should be organized. This is how your part file should be organized:

• KSP (Game root folder)
  • GameData
    • (Your mod folder name)
      • Parts
        • (Your Part Category: Utilities, Command?)
          • (Your Part Editor name like commandMk1 or RTG)
          • texture.png
          • part.cfg
          • partModel.mu (version 3 .mu)
      • Sounds (Put your sound files here)

However, as in 1.1, you can dump all your parts in the Parts folder along with its textures just fine. It is recommended, though, to use the above organization so that others can see what you're doing

You could also place multiple part configs in the same folder, whether it uses the same model or not:

• KSP/GameData/(Your mod folder name)
  • Parts
    • (Your Part Category: Utilities, Command?)
      • (Your Part Editor Identifier. Up to you)
        • texture.png
        • part.cfg
        • anotherPart.cfg
        • partModel.mu (version 3 .mu)
        • anotherpartModel.mu (version 3 .mu)
  • Sounds (Put your sound files here)

Just make sure that the name field in the cfgs are unique

Folders

KSP/GameData/(Your mod folder name)/Parts: This folder should store all the parts used in your mod. You could rename this as you want, however it's recommended to build your folder structure like so

KSP/GameData/(Your mod folder name)/Parts/(Category)/(Part Name)/: This folder contains your:

• Part cfg;
• Part model; and
• Part texture (if any)

KSP/GameData/(Your mod folder name)/sound The sound folder is optional as it is used to store sound files that a part will use during the game. Parts like engines usually have sound files with them which must be stored in this folder

Modelling

Modelling a part for KSP is quite simple enough. It's only necessary to follow the specifications and requirements to do so. When KSP imports a model, it searches for certain objects inside it. These objects are defined by their names in the 3D scene (tag name). The tag names define the function of a 3D object.

KSP also uses reference points in the 3D model to calculate coordinates for things like attachment points and the position of visual effects. Before starting a model, it's very important to consider these points: The scene scale and the model orientation. KSP works in 1 unit = 1 meter scale. So the 3D scene must be configured to use this scale as well. In 3Ds Max, this is done thought the Units Setup Menu (Customize -> Units Setup).

In practice, it's not absolutely necessary to use 1 unit = 1 meter scale in the modelling tool. Usually this is not a very convenient scale to work under, since the application is at its lowest precision limit, and problems like camera clipping may occur. It is possible, then, to work on a more comfortable scale. The exporting plugins allow for adjusting the scale factor of the exported model, and KSP allows specifying the scale factor as well through the cfg file, so coordinates can be calculated correctly when importing. The model's orientation is another point to consider. KSP, as a rocket simulator, assumes parts are modelled facing up. This includes also parts like winglets, which would be usually considered as pretty 'horizontal' things.

It is possible, however, to model a part in any orientation, and simply rotate the part before exporting. It's also possible to do it by rotating the part's pivot points, although that's not very recommended since it adds a lot of needless complexity to the part-making process.

Standards

KSP allows players to create spacecraft from the available parts. To maximize the number of possible combinations, it's necessary to follow a standard format so that a part is compatible with as high a number of other parts as possible. These standards just specify a few 'agreed upon' dimensions and values for part construction. This ensures, for instance, that cylindrical parts may be stacked over each other without any discontinuity in the stack's diameter. It's necessary, however, to have a large enough range of parts to choose from, so that it's possible to create a nice array of options to choose from. For that, we need parts of several different sizes. To make this possible, we define not one, but several standards, for each different size of part. The following tables specify the standards for stacked parts:

Also, attachment points can specify their size, so that they connect best to other attachment points of the same size.

These assume a rescaleFactor = 1 in the part config as is standard with latest Squad and modding practice.

Size 1 is the default size standard. If an attachment point does not define a size, it's assumed to be of size 1. A good idea when modelling is to import one of the stock models included with the game to your 3D scene for reference.

Making History sizes

With Making History 2 standard diameters were added: Size 1.5 and Size 4. Though they have been around in mods long before MH, they are now game-recognized standard sizes.

Size 1.5 parts use Size 2 stack nodes, presumably due to the node system not implementing non-whole-number nodes.^{[citation needed]}

Modelling with Blender

• Create your model
• Create a collision mesh
• Name the collision mesh node_collider
• Tag the collision mesh (in the editing menu - right side of the UI, triangle tab)
• Give materials to all meshes including the collision mesh - might be necessary to put two materials, because one gets "used up" for texturing
• Give a texture to all meshes
• Export to Collada

Scene Origin

The origin (point 0, 0, 0) of your 3D scene becomes the pivot point of the object in the game. It's important to consider this when modelling a part.

The pivot point is not the same as the center of mass for the part, although in many cases these points may be very close to each other. The pivot point is the point by which a part is moved when it's dragged in the Vehicle Assembly part of the game, and is also used for various flight simulation calculations. It's recommended to position the part in the 3D scene so that it's more or less centered on its center of mass. It's not necessary to find the exact center of mass of the part, but it's a good idea to place it around that point.

Materials

KSP uses the same shader for all parts. This shader is applied during the importing process, which means any material properties defined in the modelling program are discarded. It is still necessary, though, to UV map the textures onto the part. But material settings, like ambient light or specular levels are ignored. The part.cfg file allows configuring of a few key settings of the Part shader.

Important:

If you're exporting your model to .dae (COLLADA) format, you must assign materials to all exported 3D objects, including the collision mesh. These materials are discarded when the part is imported, but the game will freeze on the loading screen if the importer tries to load a .dae model that has objects without materials assigned.

For modelling convenience, we recommend applying a standard, 50% transparent material to the collision mesh.

Animations

This article is a stub. You can help KSP Wiki by expanding it.

Textures

Currently KSP only supports a single (diffuse) texture map for each part. This map can contain transparency in its alpha channel, but transparency is binary, that is, semi-transparent elements are not yet supported. It's recommended to save texture maps as PNG files.

The texture map must have power of 2 dimensions, like 256x256, 512x512 or 1024x1024. It's not recommended to use maps larger than 1024x1024. Remember your texture will be sharing video memory with several other parts.

Normal map support is planned as a feature for a future release.

Nodes and Tag Names

All nodes in KSP follow this convention:

node_[function]_[identifier]

All objects (nodes) that have a function in the model have names that start with 'node'.

the [function] section of the tag name deines the function of a node. The [identifier] section of the name defines a unique name for a node. The [identifier] section isn't always necessary, but it's used internally to identify nodes.

The following list contains the names and descriptions of each node in KSP

KSP uses the node identifiers internally to know which node is which. Since nodes are defined on a per-part basis, it relies on the following convention for attachment nodes.

node_stack_top - defines the top attachment node. node_stack_bottom - defines the bottom attachment node.

It's not absolutely necessary to name your nodes in this manner, but it's recommended doing so whenever the arrangement of nodes permits. (most cylindrical parts will be able to attach by the top and bottom, so that would be a good example of a case where the convention does apply. The Tricoupler, on the other hand, has a single top node and 3 bottom nodes, so the bottom nodes are called node_stack_bottom1, node_stack_bottom2 and node_stack_bottom3. This last example also illustrates the best way to still comply with the node naming convention even with non-standard node arrangements)

Attach Rules

Parts in KSP attach to one another in a few different ways. Parts can be Stacked (connecting by the attachment points on both parts), or Surface-Attached (aligning to the surface of other parts).

Stacking is the main mode of attachment for parts. This mode permits parts to attach themselves to predefined points (stack nodes) on other parts by their own stack nodes.

Surface-Attachment is a secondary attachment mode, which allows parts to connect themselves to others while keeping themselves aligned to the surface of the parent part. This mode can be seen used in Winglets, Radial Decouplers, and Solid Rocket Boosters.

These modes are defined through the part.cfg file for each part, through the AttachRules entry. This entry takes 5 values, that define these rules. Why use 5 values for only 2 rules? Because it's necessary to know not only how this part will connect to others, but also how other parts will connect to this one.

These are the AttachRules, in the same order as the AttachRules entry:

1. Stack
2. Surface Attach
3. Allow Stack
4. Allow Surface Attach
5. Allow Collisions

Rules 1 and 2 define how this part will connect to others. Rules 3 and 4 define how other parts will connect to this one (provided their own rules allow it). Rule 5 is a special case that defines whether or not a part can be placed while intersecting another.

Collision Mesh

The collision mesh is used to calculate collisions between a part and the world, buildings or other parts. This mesh is independent of the visual mesh, so it's possible to use a simplified model for collision detection, instead of relying on the usually much more intricate visual mesh for that purpose.

The collision mesh is identified by the tag name node_collider.

Collision mesh specifications

The collision mesh is required to be a convex solid (no concavities). That is, an O shaped collider will work, but an L shaped one won't. The importer assumes the collision mesh will be placed over the visual mesh, so they share the same coordinates and pivot point location.

Exporting the Model

Once your part is modelled and ready, it's time to export it into the game. KSP currently supports 3D models in COLLADA (.dae) and OBJ format.

In 3Ds Max, we recommend using the AutoDesk Collada exporter for .dae, or the Obj exporter. It's also possible to use the OpenCollada plugin exporter.

Each exporter plugin has its own set of settings and options, but all of them offer the needed settings for exporting to KSP.

These are the main points to consider when exporting a part:

Scale Factor

This parameter defines the scale of the model after it's exported. KSP uses 1 unit = 1 meter scale, so it's necessary to configure the exporter so that the output model has the correct scale.

If your model is in 1 unit = 1 meter scale, use a 1.0 scale factor. If your model is in 1 unit = 0.1 meters (1 decimeter) scale, use a 0.1 scale factor. If your model is in 1 unit = 1 centimeter scale, use a 0.01 scale factor. And so on...

Up-Axis

Some modelling programs (like 3Ds Max) work in different coordinate systems. KSP works under the Y-Up convention. That is, the Y axis is assumed to be pointing up.

3Ds Max (and others) use the Z-Up convention, where the Z axis is the one pointing up.

For this reason, it's necessary to set up the exporter so that it swaps the Z and Y axis, if necessary, so that the output model is oriented correctly.

In the Autodesk Collada exporter, this setting is located in the 'Axis Conversion' submenu. It should be set for Y-Up.

In the OBJ 3Ds Max exporter, this setting is changed through the 'Flip Z Axis (Poser-like)' checkbox. This box should be enabled.

Tangents and Binormals

The KSP importer does not support tangent and binormal information in the imported model. If it tries to import a model that includes this data, it's very likely it will crash and make the game freeze at the loading screen.

It's required, then, to make sure that this option is turned off in the model exporter.

KSP calculates and applies tangents internally after importing the model.

Use Single Matrix

This option is present in the Collada and Obj exporters. It should be set to off. If it's left on, the model may appear rotated in the game.

KSP Vector Tool (getVectorTool MaxScript)

Attachment nodes and FX definitions are defined in the part.cfg file. However, defining the XYZ position and orientation of each node manually can be a rather tedious job.

KSP Vector Tool is a script for 3Ds Max that facilitates this process, by automatically generating a formatted cfg entry for a node.

To install this script, check the SDK-Readme file included in the SDK package. This readme file also contains instructions on how to use the tool.learn more