Difference between revisions of "Tutorial:Creating your first module"

From Kerbal Space Program Wiki
Jump to: navigation, search
m (Robot: Changing Category:Part Module Tutorials to Category:Plugin SDK Tutorials)
(Updated for 0.18)
Line 1: Line 1:
 
So you've got your IDE all set up.  Now what?
 
So you've got your IDE all set up.  Now what?
  
The next step involves coding your first Part class.  Quit shaking, it's actually very simple to add things to KSP, and won't take you very long to complete.
+
The next step involves coding your first PartModule class.  Quit shaking, it's actually very simple to add things to KSP, and won't take you very long to complete.
  
 
'''This tutorial assumes you're using Visual Studio 2010, but any IDE will do;  Adapt accordingly!'''
 
'''This tutorial assumes you're using Visual Studio 2010, but any IDE will do;  Adapt accordingly!'''
Line 42: Line 42:
 
== The Good Stuff ==
 
== The Good Stuff ==
  
=== Extending Part ===
+
=== Extending PartModule ===
Part Modules all have one thing in common:  They extend the Part class.  The Part class defines a bunch of easy to use and intuitive methods and properties which you must override to do things with your module.
+
Part Modules all have one thing in common:  They extend the PartModule class.  The PartModule class defines a bunch of easy to use and intuitive methods and properties which you must override to do things with your module.
  
So, let's go ahead and extend Part.  You don't need to add any ''using'' statements; It's in the global namespace as long as you have your KSP DLLs referenced correctly. Note that, again, compulsive cleanup was done.  
+
So, let's go ahead and extend PartModule.  You don't need to add any ''using'' statements; It's in the global namespace as long as you have your KSP DLLs referenced correctly. However, you will need to add a ''using'' statement for the namespace UnityEngine in order to access debug functionality. Note that, again, compulsive cleanup was done.  
  
 
'''DO NOT ADD A CONSTRUCTOR, KSP DOESN'T LIKE CONSTRUCTORS!'''
 
'''DO NOT ADD A CONSTRUCTOR, KSP DOESN'T LIKE CONSTRUCTORS!'''
Line 54: Line 54:
 
using System.Linq;
 
using System.Linq;
 
using System.Text;
 
using System.Text;
 +
using UnityEngine;
  
public class TestModule : Part
+
public class TestModule : PartModule
 
{
 
{
 
}
 
}
Line 61: Line 62:
  
 
=== Showing Up to Class ===
 
=== Showing Up to Class ===
When a part module is first loaded, Part.onPartStart() is called.  Here, we can set up low-level things like icons.
+
When a part module is first loaded, PartModule.onStart() is called.  Here, we can set up low-level things like icons.
  
So, let's go ahead and override onPartStart.  You don't need the base.onPartStart() stuff, so let's toss that and add some documentation like good programmers do.  The ''override'' prefix isn't necessary, but it's good practice and will throw compile errors in case HarvesteR moves things around.
+
So, let's go ahead and override onStart.  You don't need the base.onStart() stuff, so let's toss that and add some documentation like good programmers do.  The ''override'' prefix isn't necessary, but it's good practice and will throw compile errors in case HarvesteR moves things around.
  
 
<syntaxhighlight>
 
<syntaxhighlight>
Line 70: Line 71:
 
using System.Linq;
 
using System.Linq;
 
using System.Text;
 
using System.Text;
 +
 +
using UnityEngine;
  
 
/// <summary>
 
/// <summary>
 
/// My first part!
 
/// My first part!
 
/// </summary>
 
/// </summary>
public class TestModule : Part
+
public class TestModule : PartModule
 
{
 
{
 
     /// <summary>
 
     /// <summary>
 
     /// Called when the part is started by Unity.
 
     /// Called when the part is started by Unity.
 
     /// </summary>
 
     /// </summary>
     protected override void onPartStart()
+
     public override void onStart()
 
     {
 
     {
 
     }
 
     }
Line 92: Line 95:
 
using System.Linq;
 
using System.Linq;
 
using System.Text;
 
using System.Text;
 +
 +
using UnityEngine;
 +
  
 
/// <summary>
 
/// <summary>
 
/// My first part!
 
/// My first part!
 
/// </summary>
 
/// </summary>
public class TestModule : Part
+
public class TestModule : PartModule
 
{
 
{
 
     /// <summary>
 
     /// <summary>
 
     /// Called when the part is started by Unity.
 
     /// Called when the part is started by Unity.
 
     /// </summary>
 
     /// </summary>
     protected override void onPartStart()
+
     public override void onStart()
 
     {
 
     {
 
         // Add stuff to the log
 
         // Add stuff to the log
         print("something silly to the log");
+
         Debug.Log("something silly to the log");
 
     }
 
     }
 
}
 
}
Line 114: Line 120:
  
 
* Because we're just making a simple test part, make a copy of the RCS block and edit part.cfg.   
 
* Because we're just making a simple test part, make a copy of the RCS block and edit part.cfg.   
* Now, change part.cfg so that <code>module = RCSModule</code> becomes <code>module = TestModule</code>.
+
* Now, change part.cfg so that <code>MODULE { name = ModuleRCS</code> becomes <code>MODULE { name = TestModule</code>.
* So we still have access to the old RCS, let's change the <code>name =</code> to something like ''MyUselessPart''.
+
* So we still have access to the old RCS, let's change the <code>name =</code> at the topmost level from ''RCSBlock''to something like ''MyUselessPart''.
  
 
Save the .cfg file. When you load the game, you'll discover that the RCS block is indeed there.  And it doesn't do anything.
 
Save the .cfg file. When you load the game, you'll discover that the RCS block is indeed there.  And it doesn't do anything.

Revision as of 20:24, 4 December 2012

So you've got your IDE all set up. Now what?

The next step involves coding your first PartModule class. Quit shaking, it's actually very simple to add things to KSP, and won't take you very long to complete.

This tutorial assumes you're using Visual Studio 2010, but any IDE will do; Adapt accordingly!

First Things First

You've managed to slog through Setting up Visual Studio, and you've got an empty class open in front of you with a pretty uncreative name.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
namespace MyKSPProject
{
    public class Class1
    {
    }
}

We're going to rename the class to something nice and creative, like TestModule. As a matter of good practices, remember to rename the file the class is in! (In VS2010, right-click the file and choose Rename.)

After compulsively re-indenting (VS2010: CTRL+E, D) it looks like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
public class TestModule
{
}

Awesome, now we can move on to the good stuff.

The Good Stuff

Extending PartModule

Part Modules all have one thing in common: They extend the PartModule class. The PartModule class defines a bunch of easy to use and intuitive methods and properties which you must override to do things with your module.

So, let's go ahead and extend PartModule. You don't need to add any using statements; It's in the global namespace as long as you have your KSP DLLs referenced correctly. However, you will need to add a using statement for the namespace UnityEngine in order to access debug functionality. Note that, again, compulsive cleanup was done.

DO NOT ADD A CONSTRUCTOR, KSP DOESN'T LIKE CONSTRUCTORS!

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using UnityEngine;
 
public class TestModule : PartModule
{
}

Showing Up to Class

When a part module is first loaded, PartModule.onStart() is called. Here, we can set up low-level things like icons.

So, let's go ahead and override onStart. You don't need the base.onStart() stuff, so let's toss that and add some documentation like good programmers do. The override prefix isn't necessary, but it's good practice and will throw compile errors in case HarvesteR moves things around.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
using UnityEngine;
 
/// <summary>
/// My first part!
/// </summary>
public class TestModule : PartModule
{
    /// <summary>
    /// Called when the part is started by Unity.
    /// </summary>
    public override void onStart()
    {
    }
}

So we've got a method now, but it doesn't really do anything. So, let's just print something silly to the log.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
using UnityEngine;
 
 
/// <summary>
/// My first part!
/// </summary>
public class TestModule : PartModule
{
    /// <summary>
    /// Called when the part is started by Unity.
    /// </summary>
    public override void onStart()
    {
        // Add stuff to the log
        Debug.Log("something silly to the log");
    }
}

Cool! Now when we compile the DLL (which you can find in Visual Studio 2010/YourSolution/YourProject/bin/Debug) and toss it into Plugins/

Adding to a Part

  • Because we're just making a simple test part, make a copy of the RCS block and edit part.cfg.
  • Now, change part.cfg so that MODULE { name = ModuleRCS becomes MODULE { name = TestModule.
  • So we still have access to the old RCS, let's change the name = at the topmost level from RCSBlockto something like MyUselessPart.

Save the .cfg file. When you load the game, you'll discover that the RCS block is indeed there. And it doesn't do anything.

Build and Test

Load the game, we can see something silly in our KSP_Data/output_log.txt!

Alternatively, press ALT+F2 to bring up the ingame debug console.

Continuing the Legacy

Now it's your turn. Try overriding various methods in Part, like onActiveUpdate. Over the coming weeks, more documentation will become available.