Creating a MasterPlan Add-On (Part #1)

Posted on November 1, 2010

1


A MasterPlan Add-In in two parts.

Summary

Thought I would post this, as I have had some email questions regarding this.  I didn’t find a lot of tutorials on how to build an Add-In for MasterPlan.  Some information is available here and there, and there is a forum on Facebook, but not a lot of walk-through examples.

I’m going to create an add-in that will allow us to print out an Encounter Tracking Sheet for a chosen combat encounter.  While MasterPlan has excellent DM/Player interaction and tracking tools (including exporting to inCombat 4e), sometimes you are unable to have the computer with you during the game.

The encounter Tracking page from NewbieDM's "New DM Kit"

The output of this Add-In will be a printable document that you can use to track PCs & NPCs during the encounter.  It is based on the version that is provided by NewbieDM in his “New DM Kit“.

Setup

Here’s a link to the source code for this tutorial.

I’m going to assume a few things before I begin.

  1. You’re familiar with C# (or VB) and have an IDE like Visual Studio that you can use.
  2. You have MasterPlan on your machine and have downloaded the developers kit.
  3. You are making an add-in that will not violate any copyright or intellectual property laws.  Please remember that WoTC has already had an issue with MasterPlan.  Companies don’t like to deal with issues that keep coming back, so please make sure that you are not doing anything that could be deemed as a violation of copyright, or jeopardize the use or availability of MasterPlan.

Create the Class Library

Add References.

Add References to MasterPlan and Utils.dll

Create a new Class Library project called “EncounterTrackingSheet”.  Once the project has loaded, I usually rename the “class1.cs” to “AddOnManager.cs” so that I always have an “Add-In Manager” in the namespace that I am working.

Next, add a reference to the “Utils.dll” and “masterplan.exe” file in the MasterPlan installation directory.  These hold the interfaces that we use to connect to MasterPlan at runtime.

Checking the Framework version

***  Important – MasterPlan is written using .Net 3.5, so make sure you have that on your computer.   If you are using VS2010, you should go into the properties page for the project and change the “Target framework:” drop-down to “.NET Framework 3.5“.   You may get a dialog box saying that you need to close the solution and reload it to change the framework setting.  Go ahead and do this.  MasterPlan will not work currently with a framework higher than 3.5.

Adding Code

Open up the “AddOnManager.cs” file and add:

 using MasterPlan.Extensibility;
 

to the head of the file.

Then add the IAddOn interface to the class declaration. Right-click on the Interface declaration and choose “Implement Interface”.  This will add all the required interface calls your class. Your code should look something like this:

 using System;
using System.Collections.Generic;
using System.Text;
using Masterplan.Extensibility;

namespace EncounterTrackingSheet
{
 public class AddOnManager: IAddIn
 {

 #region IAddIn Members

 public List CombatCommands
 {
 get { throw new NotImplementedException(); }
 }

 public List<ICommand> Commands
 {
 get { throw new NotImplementedException(); }
 }

 public string Description
 {
 get { throw new NotImplementedException(); }
 }

 public bool Initialise(IApplication app)
 {
 throw new NotImplementedException();
 }

 public string Name
 {
 get { throw new NotImplementedException(); }
 }

 public List<IPage> Pages
 {
 get { throw new NotImplementedException(); }
 }

 public List QuickReferencePages
 {
 get { throw new NotImplementedException(); }
 }

 public Version Version
 {
 get { throw new NotImplementedException(); }
 }

 #endregion
 }
}
 

Connecting the dots

Lets take a look at each section and see how they apply to our Add-In and how they interact with MasterPlan.

First, lets look at the simple properties.  “Name”, “Description” and “Version” should be easily inserted, with version being the biggest hassle.

“Name” is just that.  the name that we want to see in the menu under “Add-Ins” when we run MasterPlan.  “Description” will display as a tool-tip when a user mouses over the main menu item.  Change the “Name” and “Description” properties to the following:

/// <summary>
 /// Gets the name of the add-in.
 /// </summary>
 public string Name
 {
 get { return "Encounter Tracking Sheet"; }
 }

 /// <summary>
 /// Gets the description of the add-in.
 /// </summary>
 public string Description
 {
 get { return "Add-In used to create an encounter tracker for the currently loaded project."; }
 }
 

The “Version” property requires us to return the current System.Version object. This is probably to make tracking and updating add-ins easier. This may be discussed in a later post

/// <summary>
 /// Gets the version number of the add-in.
 /// </summary>
 public Version Version
 {
 get { return System.Reflection.Assembly.GetExecutingAssembly().GetName().Version; }
 }

Once we have these three Properties set to return their value, we can begin to focus on building the functionality of the add-in to do what we want it to do.

*** Important: You will have to add a returnable object to each of the properties. If you do not return an object, or return ‘null’, MasterPlan will fail to load correctly. There is a log directory that you will be able to check to see if any errors occurred in MasterPlan.

Fill in the code for the other properties:

/// <summary>
 /// Gets the list of combat commands supplied by the add-in.
 /// </summary>
 public List CombatCommands
 {
 get { return new List<ICommand>(); }
 }

 /// <summary>
 /// Gets the list of commands supplied by the add-in.
 /// </summary>
 public List<ICommand> Commands
 {
 get { return new List<ICommand>(); }
 }

 /// <summary>
 /// Gets the list of tab pages supplied by the add-in.
 /// </summary>
 public List<IPage> Pages
 {
 get { return new List<IPage>(); }
 }

 /// <summary>
 /// Gets the list of quick reference tab pages supplied by the add-in.
 /// </summary>
 public List QuickReferencePages
 {
 get { return new List<IPage>(); }
 }

Initialization

When MasterPlan starts, it does a couple of things relevant to our Add-In.  It loads all the IAddOn objects in the “\masterplan\AddIns\” directory, reads their properties, and then calls the “Initialise()” function passing the IApplication “app” object.

This is where we start to interact with MasterPlan.  When MasterPlan passes us a reference to the application, we need to grab it and store it for later use.  The “app” object gives us a way to interact and reference all of the data used by MasterPlan.

Add a field to hold the IApplication object

private IApplication _MPapp = null;

to the top of the class, then assign the passed in reference to it in the “Initialise()” function like so:

private IApplication _MPApp = null;

 /// <summary>
 /// Method which is called when the add-in is loaded into the editor.
 /// </summary>
 ///
<param name="app" />The Masterplan application interface
 /// <returns>
 /// Returns true if the add-in initialised correctly; false otherwise.
 /// </returns>
 public bool Initialise(IApplication app)
 {
 //Set bool to return whether this Add-In has initialized correctly
 bool initializeSuccessful = true;

 try
 {
 this._MPApp = app;

 }
 catch (Exception e)
 {
 initializeSuccessful = false;
 }

 return initializeSuccessful;
 }

Now we have an empty framework,  ready to go for our add-in. Compile the code, copy it to the “AddIns” directory in the MasterPlan installation folder (you may need to create this folder).  Start up MasterPlan.

Our Add-In works!

Next, we’ll look at adding commands.

Advertisements
Posted in: D&D 4e, Gaming, Software