Difference between revisions of "Part Modelling Guidelines"

Revision as of 21:48, 31 December 2015

Large portions of this page are originally incorrect or so outdated that they are no longer useable. KSP has switched to a different folder system and 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

WHATEVER YOU DO, DON'T USE THIS PAGE. IT IS HIGHLY OUTDATED AND IF YOU WANT TO LEARN HOW TO MOD, GO SEE ANOTHER TUTORIAL UNTIL THIS PAGE HAS BEEN UPDATED. THANK YOU.

Before starting to build a part, it's important to understand how your files should be organized. KSP searches for parts in a specific folder, and it assumes the files will be laid out in the following manner:

• KSP (Game root folder)
  • Parts
    • MyNewPartFolder (the name doesn't really matter, but it helps to be descriptive)
      • mesh
      • textures
        • textureMap.png
      • sound
      • part.cfg
      • partModel (.dae or .obj)
  • sounds
    • a bunch of sound files
  • Ships
    • .craft files

To build a part, the first step is to create a new folder inside the Parts folder.

Folders

KSP/Parts/MyPartFolder/mesh: You can probably tell from the diagram above that the exported 3D model is not contained in the mesh folder. This is intentional. The Mesh folder is reserved for the model in binary format (serialized). As of v0.13, KSP will serialize part models and save optimized model files inside the mesh folder. Once serialized, KSP will load the part from those files instead of using the .DAE or .OBJ model. This speeds up loading time and allows part-makers to not include the .dae or .obj files in their packages. (See Binary Mesh Files for more information).

KSP/Parts/MyPartFolder/textures: This folder holds the texture maps for the part. Currently, only one map (diffuse) is supported for the part. Normal maps are planned for later releases.

KSP/Parts/MyPartFolder/sound and KSP/sounds: The sound folder is optional. It stores sound files that a part will reproduce during the game. This folder is also redundant. It's possible to add the sound files to the KSP/sounds folder, to make the sound file available to all parts. Sounds in the MyPartFolder/sounds folder can only be accessed by the part that lives in the same folder. Sounds in the KSP/sounds folder can be accessed by all parts.

KSP/Ships: This folder stores .craft files. These files define the player-crated ships. They're generated and read by the game. It's not necessary (nor recommended) to make any changes to a .craft file

part.cfg: This file defines how a part will behave in the game. The part.cfg file is a text file, that holds a list of parameters (keys), and values. KSP uses the part.cfg file as the entry point when loading a new part. If a part folder does not contain a part.cfg file, it will not be imported.

myPartModel (.dae or .obj) This is the 3D model exported from the modelling application.

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 construccion. 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 can only be connected to other attachment points of the same size.

Standard 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.

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.