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

From Kerbal Space Program Wiki
Jump to: navigation, search
(Link to part module lifecycle)
(32 intermediate revisions by 24 users not shown)
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 module.  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 7: Line 7:
 
== First Things First ==
 
== 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.
+
You've managed to slog through [[Setting up Visual Studio]] (for Windows) or [[Setting up MonoDevelop]] (for Windows/Linux/Mac), and you've got an empty class open in front of you with a pretty uncreative name.
  
 
<syntaxhighlight>
 
<syntaxhighlight>
Line 23: Line 23:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Because Unity doesn't like namespaces very much, we're going to get rid of the namespace around the class. 
+
We're going to rename the class to something nice and creative, like '''HelloKerbinMod'''.  As a matter of good practices, remember to rename the file the class is in! (In VS2010, right-click the file and choose Rename.)
 
 
We're also 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:
 
After compulsively re-indenting (VS2010: CTRL+E, D) it looks like this:
Line 35: Line 33:
 
using System.Text;
 
using System.Text;
  
public class TestModule
+
namespace MyKSPProject
 
{
 
{
 +
    public class HelloKerbinMod
 +
    {
 +
    }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 44: Line 45:
 
== 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'' directives; It's in the global namespace as long as you have your KSP DLLs referenced correctly. However, you will need to add a ''using'' directive for the <code>UnityEngine</code> namespace 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, Unity (and, by extension, KSP) DOESN'T LIKE CONSTRUCTORS!'''
  
 
<syntaxhighlight>
 
<syntaxhighlight>
Line 56: Line 57:
 
using System.Linq;
 
using System.Linq;
 
using System.Text;
 
using System.Text;
 +
using UnityEngine;
  
public class TestModule : Part
+
namespace MyKSPProject
 
{
 
{
 +
    public class HelloKerbinMod : PartModule
 +
    {
 +
    }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
=== 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(StartState state) 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 <code>OnStart</code>. You don't need the <code>base.OnStart()</code> stuff, so let's toss that and add some documentation like good programmers do.  The <code>override</code> modifier isn't necessary, but it's good practice and will throw compile errors in case HarvesteR moves things around.
  
 
<syntaxhighlight>
 
<syntaxhighlight>
Line 72: Line 77:
 
using System.Linq;
 
using System.Linq;
 
using System.Text;
 
using System.Text;
 +
using UnityEngine;
  
/// <summary>
+
namespace MyKSPProject
/// My first part!
 
/// </summary>
 
public class TestModule : Part
 
 
{
 
{
 
     /// <summary>
 
     /// <summary>
     /// Called when the part is started by Unity.
+
     /// My first part!
 
     /// </summary>
 
     /// </summary>
     protected override void onPartStart()
+
     public class HelloKerbinMod : PartModule
 
     {
 
     {
 +
        /// <summary>
 +
        /// Called when the part is started by Unity.
 +
        /// </summary>
 +
        public override void OnStart(StartState state)
 +
        {
 +
        }
 
     }
 
     }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
For what OnStart etc does, see the part module lifecycle (https://forum.kerbalspaceprogram.com/index.php?/topic/145340-the-lifecycle-of-a-part-module-a-primer/).
  
 
So we've got a method now, but it doesn't really do anything.  So, let's just print something silly to the log.
 
So we've got a method now, but it doesn't really do anything.  So, let's just print something silly to the log.
Line 95: Line 106:
 
using System.Text;
 
using System.Text;
  
/// <summary>
+
using UnityEngine;
/// My first part!
+
 
/// </summary>
+
namespace MyKSPProject
public class TestModule : Part
 
 
{
 
{
 
     /// <summary>
 
     /// <summary>
     /// Called when the part is started by Unity.
+
     /// My first part!
 
     /// </summary>
 
     /// </summary>
     protected override void onPartStart()
+
     public class HelloKerbinMod : PartModule
 
     {
 
     {
         // Add stuff to the log
+
         /// <summary>
        print("something silly to the log");
+
        /// Called when the part is started by Unity.
 +
        /// </summary>
 +
        public override void OnStart(StartState state)
 +
        {
 +
            // Add stuff to the log
 +
            print("Hello, Kerbin!");
 +
        }
 
     }
 
     }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Cool! Now when we compile the DLL (which you can find in Visual Studio 2010/YourSolution/YourProject/bin/Debug) and toss it into Plugins/ and load the game, we can see something silly in our KSP_Data/output_log.txt!
+
Cool! Now compile the DLL and find it - it should be YourSolution/YourProject/bin/Debug/MyKSPProject.dll. To install it, create GameData/MyKSPProject/Plugins/ inside KSP's GameData/ directory, and drop the DLL in your new Plugins/ directory.
  
 
== Adding to a Part ==
 
== Adding to a Part ==
  
So your part works, sort of, but you want to see it do whatever it does when you're flying.
+
=== By copying a part ===
 +
 
 +
* Because we're just making a simple test part, make a copy of the "RCS block" directory and edit part.cfg.  (As of 1.4.3, located in GameData\Squad\Parts\Utility and named rcsBlockRV-105)
 +
* Now, change part.cfg so that <code>MODULE { name = ModuleRCS</code> becomes <code>MODULE { name = HelloKerbinMod</code>.
 +
* Our part needs a name. Change the <code>name =</code> at the top of the file 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.
 +
 
 +
=== Or using ModuleManager ===
 +
 
 +
Alternately, you could begin as you should continue and use ModuleManager - a separate download - to patch the module into an existing part. Install ModuleManager.dll to GameData/ if you don't already have it.
 +
 
 +
Now create a new GameData/MyKSPProject/HelloKerbinMod_rcs.cfg file with Notepad++ or a similar text editor. Its contents should be:
 +
 
 +
<syntaxhighlight>
 +
// Modify the stock part "RCSBlock" from GameData/Squad/Parts/Utility/rcsBlockRV-105/rcsBlockRV-105.cfg
 +
@PART[RCSBlock]
 +
{
 +
        // Add a new module
 +
        MODULE
 +
        {
 +
                // using the HelloKerbinMod PartModule subclass
 +
                name = HelloKerbinMod
 +
        }
 +
}
 +
</syntaxhighlight>
 +
 
 +
When you start KSP, existing RCS thrusters will now have your new module too!
 +
 
 +
== Build and Test ==
 +
 
 +
Load the game, we can see something silly in our KSP.log and/or our output_log.  (See https://forum.kerbalspaceprogram.com/index.php?/topic/83212-how-to-get-support-read-first/ for details on where to find the game logs).
 +
 
 +
Alternatively, press ALT+F12 to bring up the ingame debug console. It might've scrolled off though.
 +
 
 +
== Common Problems ==
  
* Because we're just making a simple test part, make a copy of the RCS block and edit part.cfg.
+
Verify your project targets .NET 3.5 - many newer compilers and IDEs target 4.0. (Not relevant for newer KSP; 1.4.x uses Unity 2017 with .NET 4.5).
* Now, change part.cfg so that <code>module = RCSModule</code> becomes <code>module = TestModule</code>.
 
* So we still have access to the old RCS, let's change the <code>name =</code> to something like ''MyUselessPart''.
 
  
Save and load the game, and you'll discover that the RCS block is indeed there. And it doesn't do anything.
+
Linux systems may be missing the PCL assembly libraries, which will cause compilation to fail due to their absence. Check the [[Setting_up_MonoDevelop#PCL_assemblies_for_Linux_systems|Setting up MonoDevelop]] page for more information. (No longer an issue in newer Mono, so only try to fix it if you have a problem).
  
 
== Continuing the Legacy ==
 
== 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.
+
Now it's your turn.  Try overriding various methods in PartUpdate, like onUpdate.  Over the coming weeks, more information can be found at [[Plugins]].
  
[[Category:Tutorials]]
+
[[Category:Tutorials|{{PAGENAME}}]]
[[Category:Part Module Tutorials]]
+
[[Category:Plugin SDK Tutorials]]

Revision as of 14:06, 16 June 2018

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 (for Windows) or Setting up MonoDevelop (for Windows/Linux/Mac), 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 HelloKerbinMod. 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;
 
namespace MyKSPProject
{
    public class HelloKerbinMod
    {
    }
}

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 directives; It's in the global namespace as long as you have your KSP DLLs referenced correctly. However, you will need to add a using directive for the UnityEngine namespace in order to access debug functionality. Note that, again, compulsive cleanup was done.

DO NOT ADD A CONSTRUCTOR, Unity (and, by extension, KSP) DOESN'T LIKE CONSTRUCTORS!

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using UnityEngine;
 
namespace MyKSPProject
{
    public class HelloKerbinMod : PartModule
    {
    }
}

Showing Up to Class

When a part module is first loaded, PartModule.OnStart(StartState state) 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 modifier 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;
 
namespace MyKSPProject
{
    /// <summary>
    /// My first part!
    /// </summary>
    public class HelloKerbinMod : PartModule
    {
        /// <summary>
        /// Called when the part is started by Unity.
        /// </summary>
        public override void OnStart(StartState state)
        {
        }
    }
}

For what OnStart etc does, see the part module lifecycle (https://forum.kerbalspaceprogram.com/index.php?/topic/145340-the-lifecycle-of-a-part-module-a-primer/).

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;
 
namespace MyKSPProject
{
    /// <summary>
    /// My first part!
    /// </summary>
    public class HelloKerbinMod : PartModule
    {
        /// <summary>
        /// Called when the part is started by Unity.
        /// </summary>
        public override void OnStart(StartState state)
        {
            // Add stuff to the log
            print("Hello, Kerbin!");
        }
    }
}

Cool! Now compile the DLL and find it - it should be YourSolution/YourProject/bin/Debug/MyKSPProject.dll. To install it, create GameData/MyKSPProject/Plugins/ inside KSP's GameData/ directory, and drop the DLL in your new Plugins/ directory.

Adding to a Part

By copying a part

  • Because we're just making a simple test part, make a copy of the "RCS block" directory and edit part.cfg. (As of 1.4.3, located in GameData\Squad\Parts\Utility and named rcsBlockRV-105)
  • Now, change part.cfg so that MODULE { name = ModuleRCS becomes MODULE { name = HelloKerbinMod.
  • Our part needs a name. Change the name = at the top of the file 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.

Or using ModuleManager

Alternately, you could begin as you should continue and use ModuleManager - a separate download - to patch the module into an existing part. Install ModuleManager.dll to GameData/ if you don't already have it.

Now create a new GameData/MyKSPProject/HelloKerbinMod_rcs.cfg file with Notepad++ or a similar text editor. Its contents should be:

// Modify the stock part "RCSBlock" from GameData/Squad/Parts/Utility/rcsBlockRV-105/rcsBlockRV-105.cfg
@PART[RCSBlock]
{
        // Add a new module
        MODULE
        {
                // using the HelloKerbinMod PartModule subclass
                name = HelloKerbinMod
        }
}

When you start KSP, existing RCS thrusters will now have your new module too!

Build and Test

Load the game, we can see something silly in our KSP.log and/or our output_log. (See https://forum.kerbalspaceprogram.com/index.php?/topic/83212-how-to-get-support-read-first/ for details on where to find the game logs).

Alternatively, press ALT+F12 to bring up the ingame debug console. It might've scrolled off though.

Common Problems

Verify your project targets .NET 3.5 - many newer compilers and IDEs target 4.0. (Not relevant for newer KSP; 1.4.x uses Unity 2017 with .NET 4.5).

Linux systems may be missing the PCL assembly libraries, which will cause compilation to fail due to their absence. Check the Setting up MonoDevelop page for more information. (No longer an issue in newer Mono, so only try to fix it if you have a problem).

Continuing the Legacy

Now it's your turn. Try overriding various methods in PartUpdate, like onUpdate. Over the coming weeks, more information can be found at Plugins.