Unity to KSP: A Detailed Tutorial

[trekkie_]

Before you start

This tutorial is designed for those entirely new to Unity and its interface. There are some things to take into consideration before using Unity.

-The texturing on your models should look exactly how you want it to before you import into Unity.

-OBJ should be your model format of choice, as you may get different issues with different formats. But you are free to use any format Unity supports.

-Export models in the measurement of meters, size them appropriately.

-Zero out your models XYZ coordinates in your modeling program before exporting. All coordinates and orientations carry over to Unity, but will be considered as 0,0,0 even if it's off center.

-A mesh collider is what the game world considers a solid object. Keep all parts you intend to use as colliders, under 255 polygons. You may need to split sections of your model to meet this criteria but you can have as many individual colliders as you want.

Download

You will need Unity and the KSP Part tools package.

Unity: http://unity3d.com/unity/download/

Part Tools 18 package: http://kerbalspaceprogram.com/files/ksp-parttools-18.zip

Setup & Configuration

After you've installed Unity, extract the file in the Part Tools zip to where you installed Unity.

For Example: C:\Program Files\Unity\Editor\Standard Packages\

Open Unity.

You should get a prompt box with 2 tabs. If not, go to File > New Project.

Select the Create New Project tab. Select the PartTools 18.unitypackage and click Create. There will be some loading bars as it prepares the project.

On the bottom left, there is a [Project] tab with a list of some folders.

This is the file explorer for your project. To the right of that in the bottom center, is the area where you will see file listings of what is contained in each folder.

Right click the Assets folder then go to Create > New Folder. Name this folder whatever you want. This will be the folder you will drag and drop model and texture files into. It's best to have a separate folder for each mod you'll be making.

Now go to the Plugins > KSP folder.

In it there is a file named PartTools. This contains the script that allows you to export models and textures from Unity to KSP properly. But we will cover the usage of that later.

Create a New Gameobject, either by going to the top menu bar; GameObject > Create Empty, or pressing ctrl+shift+N.

This will create a new object in the [Hierarchy] panel on the top left of Unity. Rename this object "PartTools" for simplicity sake.

Drag the Part Tools file into the [Hierarchy] panel on the upper left, drop it into the GameObject you just created and renamed.

Now That all of these steps have been completed, Unity is completely setup for KSP. This would be a good time to save the project. Go to File > Save Project.

Getting Started

Open the folder you created in the Assets folder earlier. Drag and drop your model, .mtl (if applicable) and texture files into the bottom center panel (or directly on the folder).

You should now see your model and textures in the file listing, along with a folder named Materials.

Select your model from the list then drag and drop it anywhere in the [Hierarchy] panel.

The model will now show listed under your Main Camera and be visible in the center window named [scene]. There will be an arrow triangle next to the name.

This can be clicked and will show a named listing of the individual parts of your model, and selecting any of them will automatically select that specific part of the model for working with. Alternatively, you can select individual parts or groups of a model visually from the display in the [scene] panel in the middle center of Unity.

There is a panel on the right side of Unity called the [inspector] panel.

Any file or part you have selected, either from the [Hierarchy] or [Project] panels, will show options in the [inspector] panel. These options are referred to as Components.

Import Settings

Select the model from the [Project] panel's file explorer. This will reveal the Import Settings options for your model in the [inspector] panel.

Set Scale factor to 0.1 or 1.0. This setting depends on the scaling and sizing of your model when you exported from your modeling program. 0.1 is considered default.

Check Generate colliders and Generate Lightmap UVs.

APPLY the settings.

There are other options here, but we will not cover them. Not all of these options are necessary or the values can be changed, but it's best to keep them this way by default. You will have to apply these settings to every new model you import.

Mesh Colliders, Textures & Shaders

Now we will go back to the [Hierarchy] panel on the top left. From there we will select each part of our model individually, starting with the first one from the list. The part will indicate it is selected visually in the [scene] panel in the top center of Unity.

On the Right, in the [inspector] panel, you will notice options appear once you've selected the part.

The two basic Components we will be working with are the Mesh Collider and Materials. The mesh collider component can be found through the Add Component button at the bottom of the [inspector] panel. Specifically under Add Component > Physics > Mesh Collider.

This will add the component options to the [inspector] panel strictly for the part you have selected.

The Material options should already be visible in the [inspector] panel without having to add it as a Component, as long as any part of your model is already selected.

First we will be working with the Materials options. At the top of the materials section of the panel, it will say Shader: with a drop down box. Browse through the drop down box and select KSP. You must select and use one of the KSP shaders with your part, and can use different shaders with different parts of any given model as long as they can be selected individually.

There will be several different shader options to choose from. Specular for example, makes your model surface shiny. Diffuse makes your model surface dull. I will not go into detail explaining all of the other shaders and their different settings since this tutorial assumes you know what most of these terms mean.

Note: You can also access an area to apply a texture with any of the colored sphere icons in the Materials folder, which will bring up the material options in the [inspector] panel.

To the right in the material options, you'll see a blank box with a Select button on the right.

Clicking Select will allow you to choose from any textures you dragged and drop into your project.

Selecting any texture will assign it to that specific part, which should be visually apparent immediately. You must repeat this process for each section you're adding textures to.

Now we will cover the Mesh Collider. Go to Add Component > Physics > Mesh Collider if you haven't already. This will bring up a new set of options in the [inspector] panel.

There will be a few options to choose from, but we will only cover the basic options you need to set. There will be an option called Convex. This option must be set on all parts with a mesh collider. Below that you will see a Mesh selection option, this is where you select the part of a model to assign the mesh collider to.

To bring up the mesh selection listing, click the circle on the right

Select the part you are currently working with if it isn't already selected. Repeat this process for each part that needs a mesh collider.

Parts with a mesh collider will be visually wrapped in green lines along their vertices.

Export to KSP

Go to the [Hierarchy] and select the Part Tools object we created earlier. In the [inspector] panel you will see the Part Tools script options.

Set Part Name to whatever you wish, but try to make it unique so it doesn't conflict with other KSP parts. The File Path will be the name of the folder created, which is the folder that you will put into the "Parts" directory of a KSP installation.

Leave the File name and File extension as it is, never change these. Make sure Copy Textures and Convert Texture options are always checked just in case.

Set your Texture Format to either PNG OR MBM. Now Click Write. This will export your now KSP compatible model and textures to your Unity projects folder, which is in your 'My Documents' folder by default. Example: My Documents\New Unity Project\Parts\

Your project is now complete and you may copy the File Path folder into the KSP installations Parts folder through your operating systems file explorer. Add a suitable Parts.cfg file to the part folder. The part name you set in the config file should be the same as the one you used when writing your part.

Your textured model should now be accessible in the game.

Notes:

-If something isn't done properly, you may get an error listing in the Console area (found right beside the Project panel) when trying to Write. Errors may cause a non functional model file that will not load in KSP or cause KSP to hang on loading. This tutorial however, does not cover error troubleshooting.

-Sometimes models may seem invisible within KSP. This is usually due to the model being scaled too large or too small, or if textures are either missing or not assigned properly. You can alter scale either in your modeling program, unity, or the part.cfg file.

-Part.cfg settings do not fall under the scope of this tutorial.

-The Part Tools script will export all parts in the Hierarchy; make sure to remove completed mods from the Hierarchy if working on new ones.

-Make sure all XYZ coordinates in Unity are also zero'd out before writing your part, since the coordinates will carry over to KSP and could cause everything to be off center, including attachment points.

Edited May 2, 2013 by trekkie_

[ahappydude]

Thank you =) Alot of usefull infomation

[EndlessWaves]

I would replace the mediafire link to the part tools with the official one: http://kerbalspaceprogram.com/files/ksp-parttools-18.zip

It's probably not best practice to drop it onto the Main Camera object, KSP 0.19.1 renames it the root object to model and doesn't include camera components in the current version but there's no guarantee that won't change in future (even if it does seem unlikely).

You shouldn't be using a mesh collider for a cube, a box collider will give better performance.

As far as I know there's no reason to use MBM textures currently, and you can always convert later if there is. I'd leave it on PNG.

[Technical Ben]

Thanks. I'll read through this in due course. Are you happy if I use this for some video examples? I'm planning to do the artwork myself mind...

[trekkie_]

I would replace the mediafire link to the part tools with the official one: http://kerbalspaceprogram.com/files/ksp-parttools-18.zip

It's probably not best practice to drop it onto the Main Camera object, KSP 0.19.1 renames it the root object to model and doesn't include camera components in the current version but there's no guarantee that won't change in future (even if it does seem unlikely).

You shouldn't be using a mesh collider for a cube, a box collider will give better performance.

As far as I know there's no reason to use MBM textures currently, and you can always convert later if there is. I'd leave it on PNG.

thanks for the link.

I put part tools in the main camera simply because it stays there. I used to just drag and drop it onto the model itself, but if you need to re-work the model in your modeling program and remove it from the camera then re-add it to the project, you must drop the part tools back into the model again.

to me, it's efficient to just let it sit in the camera view because it allows you to 1) not have to keep dragging and dropping it onto individual models 2) use it with any model you have in the main camera. Of course, It would probably be just as easy to create a new blank hierarchy object named "part tools" and use it from there.

Edited April 20, 2013 by trekkie_

[hoojiwana]

Since this tutorial is much better than the one I did, I've changed the thread I had over into a modding-info collection point of sorts, and I've put a link to this over there. Whether people will use my thread I have no idea, at the very least I will.

[Devo]

You don't explain the diff between convex mesh colliders and normal ones, thats handy.

[trekkie_]

You don't explain the diff between convex mesh colliders and normal ones, thats handy.

it's not really necessary when the only thing you should set it is convex. it's one of those settings that doesn't hurt to be always checked, but can hurt if it isn't. I can't think of a reason why if someone even knew the difference, that they would want to use a non convex collider for unity and ksp at all anyways. now that I think about it, it would probably be bad practice for mod makers and users in general if non convex parts started flooding the game.

Edited April 20, 2013 by trekkie_

[Devo]

it's not really necessary when the only thing you should set it is convex.

That's not a steadfast rule for me, Normal colliders can save you the pain of splitting up objects to make multiple convex colliders. I.e a cargo bay. You can't convex the bay can you? it will cover the opening,

so you either make all the walls and sides seperate convex colliders, or simply use a convex base and the rest normal colliders. All convex does for me is ensure things dont fall through it or it

doesnt fall through the floor, I use a combination of both. But good tutorial, ill let you carry on. I guess everyone has their own way of doing things.

Like texturing for example.. you mention

"Paint your models with textures in your modeling application, using domains for the surfaces you're painting (UV mapping). The texturing should look exactly how you want it to before you import into Unity.

"

Doesn;t really make any sense to me as I do my texturing in a completely different fashion, but I guess thats the beauty of blender and unity, 10 ways to achieve the same result!

[trekkie_]

That's not a steadfast rule for me, Normal colliders can save you the pain of splitting up objects to make multiple convex colliders. I.e a cargo bay. You can't convex the bay can you? it will cover the opening,

so you either make all the walls and sides seperate convex colliders, or simply use a convex base and the rest normal colliders. All convex does for me is ensure things dont fall through it or it

doesnt fall through the floor, I use a combination of both. But good tutorial, ill let you carry on. I guess everyone has their own way of doing things.

Like texturing for example.. you mention

"Paint your models with textures in your modeling application, using domains for the surfaces you're painting (UV mapping). The texturing should look exactly how you want it to before you import into Unity.

"

Doesn;t really make any sense to me as I do my texturing in a completely different fashion, but I guess thats the beauty of blender and unity, 10 ways to achieve the same result!

I see what you mean now. of course this tutorial is meant to familiarize beginners with the unity interface more than anything, and get them started with the basics of transporting models to ksp, basics do's and don't, pre-requisites, etc. i wouldn't really expect a beginner to start off with something like moving cargo bay doors or something that is ok for other meshes to pass through, and there's plenty of easy access information if they did come across the problem of needing a part to ignore other mesh's.

sometimes you gotta try not to get too detailed, for example I didn't explain the difference between PNG or MBM textures. I wouldn't consider that a gap, I'd consider that efficiency. sometimes too much info, especially info that may not apply to most usage scenario's, can confuse and distract the novice with information overload. I know I've had frustrations having to sort through information to get to the essential relevant bits.

I personally don't use blender, but I'm pretty sure face domains (without the single UV map texture file) are common to all modeling programs. I think there's really only two main ways to texture. domains are a form of uv mapping, without the actual single map of all the models textures in one file. You select faces to apply a texture to and it just keeps track of the orientation and alignment settings (i.e. parametric, box, cylindrical, etc) of the separate raw texture files, and the faces they apply to. there is no consolidated file with all the textures. typically unity will automatically show an imported model fully textured already if the domain'd textures are included before or when the model is added.

the added benefit of this is that you can change out textures in unity and still have them follow the alignment you set when you saved the model. so maybe something has a gold texture and I want to make it a silver texture, even in unity I can just easily swap them seamlessly rather than having to go back to the modeling program and create an entirely new uv map if I want to change one part of a models texturing.

Edited April 21, 2013 by trekkie_

[hoojiwana]

I think what devo was referring to was that you said:

Paint your models with textures in your modeling application

You can do it that way, or create the texture in an external program and then import that later.

[trekkie_]

I think what devo was referring to was that you said:

You can do it that way, or create the texture in an external program and then import that later.

ah well that would be a simple re-wording fix. I just didn't want to give the impression that you can just import a blank model and expect to texture it properly from the ground up in unity, which is something I could see a novice attempting.

personally, my modeler has robust UV mapping tools built-in. pretty sure blender does too. never saw the need for programs like uvmapper pro, little too old school

Edited April 21, 2013 by trekkie_

[ghost010]

May i advice to change the"part tools bit" as putin it on the main camera,will export the main camera...

i discovered this because it didnt export any textures and was done in 0.1 second if not faster.

(i never put any objects inside the main camera,never should any one do so)

[trekkie_]

May i advice to change the"part tools bit" as putin it on the main camera,will export the main camera...

i discovered this because it didnt export any textures and was done in 0.1 second if not faster.

(i never put any objects inside the main camera,never should any one do so)

have never had a problem with it before. as endlesswave said, it's unlikely they will implement anything in future versions having anything to do with the main camera being a parent.

perhaps your issue was because of something else causing a bad model.mu to be produced? can you give me an example of what kind of problem this would cause? all of my released mods have main camera part tools, and they show up fine in the game.

Edited April 21, 2013 by trekkie_

[Devo]

the added benefit of this is that you can change out textures in unity and still have them follow the alignment you set when you saved the model. so maybe something has a gold texture and I want to make it a silver texture, even in unity I can just easily swap them seamlessly rather than having to go back to the modeling program and create an entirely new uv map if I want to change one part of a models texturing.

If I need to change out textures, I do that all in blender not in unity really, by that point everything is done and ready to go in there. All unity is used for for me is to drag and drop the assets onto the model. I never have to create a new UV map in blender for a texture change, that's where the 'replace image' feature comes i handy for me I guess. The models still follow the alignment of the texture and you can export to unity and simply import a new texture and apply it and it works fine.

[Zaeo]

You also may want to note in for modules to be called, a "create empty" with the name of the module is necessary.

For example, for a "intake air" part I am designing, I had to add 4 "empty" units in the position of the vents, and name them all "Intake" This is within the GameObject, but on the same level as the model.

After this has been done, KSP will recognize the "intake transform" and function properly.

Example:

MODULE

{

name = ModuleResourceIntake

resourceName = IntakeAir

checkForOxygen = true

area = 0.002

intakeSpeed = 10

intakeTransformName = Intake

}

RESOURCE

{

name = IntakeAir

amount = 0.2

maxAmount = 0.2

}

You can name "Intake" Anything, but it has to be named the same as the one you chose in unity.

[trekkie_]

If I need to change out textures, I do that all in blender not in unity really, by that point everything is done and ready to go in there. All unity is used for for me is to drag and drop the assets onto the model. I never have to create a new UV map in blender for a texture change, that's where the 'replace image' feature comes i handy for me I guess. The models still follow the alignment of the texture and you can export to unity and simply import a new texture and apply it and it works fine.

ok, other than what hooji was saying, what did you mean about texturing differently then?

[trekkie_]

You also may want to note in for modules to be called, a "create empty" with the name of the module is necessary.

For example, for a "intake air" part I am designing, I had to add 4 "empty" units in the position of the vents, and name them all "Intake" This is within the GameObject, but on the same level as the model.

After this has been done, KSP will recognize the "intake transform" and function properly.

Example:

MODULE

{

name = ModuleResourceIntake

resourceName = IntakeAir

checkForOxygen = true

area = 0.002

intakeSpeed = 10

intakeTransformName = Intake

}

RESOURCE

{

name = IntakeAir

amount = 0.2

maxAmount = 0.2

}

You can name "Intake" Anything, but it has to be named the same as the one you chose in unity.

it's good info, but i don't think it belongs here. that's not really the scope of the tutorial....it's not a how to make every part tutorial. if i did that, then i'd have to explain thrust transforms, and ladder boxes, part triggers, orientations, layer 21, tags, etc. the ksp wiki already has pages and pages devoted to that.

i however will probably alter to tutorial for the part tools to be put in an empty game object.

[ummwut]

Thanks for the post, kerbtrek!

[ghost010]

well it exported fine when i added the part tools part to the mesh/object parent.

i never make my main camera as a parent.

Its a workflow principle when using unity.

Maybe it did not export with the camera because you used the main camera as parent object(putting objects inside main camera).

[Sardu]

Anyone have this working on a mac? When I get the parttools its just a normal zip and when I unzip the file it comes out as a normal folder and I'm not able to get it installed in unity the way this tut has you do it.

[EndlessWaves]

Anyone have this working on a mac? When I get the parttools its just a normal zip and when I unzip the file it comes out as a normal folder and I'm not able to get it installed in unity the way this tut has you do it.

It sounds like your unzip utility is trying to be 'helpful' by doing stuff you didn't tell it to do and extracting the unitypackage. I would recommend switching to a decent one but if you don't want to do that then you can probably zip the folder up up and rename it to Partools.unitypackage

[Sardu]

It sounds like your unzip utility is trying to be 'helpful' by doing stuff you didn't tell it to do and extracting the unitypackage. I would recommend switching to a decent one but if you don't want to do that then you can probably zip the folder up up and rename it to Partools.unitypackage

Thanks for the tip, I downloaded iZip and it was as you said, the default archival app was trying to be "helpful" thanks again

Edited April 30, 2013 by Sardu

[trekkie_]

bumpy bumpsterton

[RychschaX]

I am having some difficulties with exporting the model and textures for my new part (which is unlikely to ever be published, and is simply to help me master the workflow of developing parts for KSP).

specifically, my textures refuse to export, and I am unsure as to exactly what I am supposed to do for the collision.

I appear to have followed all of the required steps for the materials portion of the tutorial, though the tutorial is somewhat unclear as to what folder the textures themselves should be in (the root part folder, or the materials folder). nevertheless, I have applied the texture to the model in the hierarchy, but when i click "write" in the part tools, it completes instantaneously and creates the parts folder in the project directory. however, there is only the model.mu file and nothing else. Any ideas? I can post a screen cap if you wish (just tell me what you want to be selected).

I am also a bit confused regarding collision meshes. In accordance with the modeling guide on the wiki, I have my model, as well as a convex mesh I wish to use for collision named "node_collider". here is what I am confused about: first, there was already a "mesh collider" in the inspector for my main model. was this supposed to happen (perhaps due to the name of the collision mesh)? second, when selecting the mesh under the mesh collider section of the inspector for my main model, I should choose my node_collider object, correct? also, what should I do to my node_collide object?