Introduction

The AddAndRemoveVariablesForType event allows plugins to add and remove variables from standard elements. Since Gum is designed to work with external engines the properties presented by standard types (such as Sprite) may not align with the feature set of the external engine. Variables can be added and removed to create a more natural development experience for users of Gum.

Code Example

The following code can be used to add a variable to the Sprite standard element. This variable will be a float variable with the name "MyCustomVariable".

First the event must be added in the StartUp method:

  public override void StartUp()
  {
      this.AddAndRemoveVariablesForType += HandleAddAndRemoveVariablesForType;
  }

The HandleAddAndRemoveVariablesForType method handles the event being raised and adds the necessary variables. Note that in this case we are only handling variables for the Sprite type, but the same method could be used for all types:

private void HandleAddAndRemoveVariablesForType(string type, Gum.DataTypes.Variables.StateSave stateSave)
{
    if (type == "Sprite")
    {
        // Add startup logic here:
        var variableToAdd = new Gum.DataTypes.Variables.VariableSave();
        variableToAdd.Name = "MyCustomVariable";
        variableToAdd.Type = "float";
        variableToAdd.Value = 1.0f;
        variableToAdd.IsFile = false;
        variableToAdd.Category = "Plugin 1 Category";
        // We must mark this as true if we want the default value to be used:
        variableToAdd.SetsValue = true;

        stateSave.Variables.Add(variableToAdd);
    }
}

The end result would be that the Sprite object displays the variable when selected:

Variable removal

The example above shows how to add variables, but you can also remove variables from standard types. For example if your engine does not support texture wrapping on Sprites, you may do the following:

private void HandleAddAndRemoveVariablesForType(string type, Gum.DataTypes.Variables.StateSave stateSave)
{
    if (type == "Sprite")
    {
        var variableToRemove = stateSave.Variables.FirstOrDefault(item => item.Name == "Wrap");

        stateSave.Variables.Remove(variableToRemove);
    }
}

To prevent accidental deletion of data, Gum will still present variables which are defined in the XML files for standard elements even if the variable is removed through a plugin. Therefore, to fully remove a variable (like Wrap), it must be removed from the underlying XML file as well. This can be done by removing the individual file from the XML file, or deleting the entire XML file (which will cause Glue to regenerate it). Keep in mind that deleting and regenerating the entire XML file will result in all other changes being lost.

Additional Examples

The syntax used to add new variables in plugins is the same as how Gum adds standard properties. For an extensive example on how to add variables, see the StandardElementsManager.Initialize method.

Introduction

The Export delegate allows you to create a custom export for Gum elements. This delegate will automatically be called by Gum whenever an element is saved. By default this occurs whenever the user makes any modification to the element. If your export is especially processor intensive you may consider not adding your export logic here and rather requiring an explicit export by the user.

Code Example

The following code will show a message box whenever an element is exported. Keep in mind this is only for demonstration purposes. By default Gum auto-saves every change made by the user, and showing a message box after every save can be very annoying for users of your plugin.

        public override void StartUp()
        {
            this.Export += HandleElementExport;
        }

        void HandleElementExport(Gum.DataTypes.ElementSave element)
        {
            System.Windows.Forms.MessageBox.Show("Handling export of " + element);
        }

Accessing properties

The above example shows how to react to a component being exported, but it doesn't get at the heart of what an export plugin does.

The first thing that an export plugin needs to do is to access properties on an element (such as its position and size) as well as the instances contained within the element. This information is available through the ElementSave class.

For more information on how to access properties and instances from the ElementSave, see the Gum Class Overview page.

Example Export Code

The following shows what a very simple exporter might look like:

        void HandleElementExport(Gum.DataTypes.ElementSave element)
        {

            StringBuilder stringBuilder = new StringBuilder();

            foreach(var instance in element.Instances)
            {
                stringBuilder.AppendFormat("{0} {1} = new {0}();", 
                     instance.BaseType, instance.Name);   
            }

            stringBuilder.AppendLine();

            // We'll just use the default state for this example:
            foreach(var variable in element.DefaultState.Variables)
            {
                if(variable.Value != null && variable.SetsValue)
                {
                   // You may want to process the Value.  For example,
                   // if it's a float, the string representation of the 
                   // value might be "1.23", but you may want to convert that to
                   // "1.23f"
                   // Similarly strings may need to be wrapped in quotes, and values like
                   // coordinate types may need to be qualified as enumerations or
                   // translated into whatever system the given engine uses.
                   string rightSideOfEquals = variable.Value.ToString();

                   stringBuilder.AppendFormat("{0} = {1};", 
                          variable.Name, rightSideOfEquals);
                }
            }

            string textToSave = stringBuilder.ToString();

            // Now the textToSave would get saved to disk wherever you want it exported
        }

This may produce output that looks like this:

Sprite SpriteInstance1 = new Sprite();
Sprite SpriteInstance2 = new Sprite();
Text TextInstance1 = new Text();

SpriteInstance1.X = 3;
SpriteInstance1.Y = 4;
SpriteInstance2.Width = 10;
Text.X = 3;

Introduction

This page discusses how to write plugins for Gum. Plugins are a useful way to modify Gum because they allow you to customize Gum without making project-specific, technology-specific, or organization-specific modifications to the core source code. This means that you can customize the Gum experience while still maintaining ties to the core source code.

Setup

To begin writing a plugin:

1. Obtain the Gum source code. You can download the .zip or get the source through a version control client

2. Create a copy of Gum.sln. You will want to work with your own .sln file so that the project containing your plugin can be debugged easily. For example, you might want to call your solution GumWithPlugins.sln

3. Open your new .sln file in Visual Studio

Now that you have created a .sln which will contain your plugin project, you can add this project:

1. Right-click on your solution

2. Select "Add ->New Project..."

3. Select "Class Library" as the type

4. Verify that you are targeting .NET 4.5

5. Enter the name of your project, such as MyPluginProject

6. Click OK

Next you'll need to reference the Gum libraries. To do this:

1. Right-click on your project's References

2. Select "Add Reference"

3. Verify that "Solution" is selected (Assuming Visual Studio 2012)

4. Check the following projects:

   1. Gum

   2. GumDataTypes

   3. InputLibrary

   4. RenderingLibrary

   5. ToolsUtilities

5. Click OK

Since Gum references XNA, and XNA doesn't have 64 bit libraries, you will need to modify your project's build configuration. To do this:

1. Select the "Build"->"Configuration Manager" menu item

2. Change the Active solution platform" from "Mixed Platforms" to "x86" if it isn't already set to x86. If your Active solution is set to "Any CPU", change that to "x86"

3. If your plugin project's Platform is set to "Any CPU", use the drop down to pick "x86" if it exists. If not, select ""

   1. Change the New platform to "x86"

   2. Click "OK"

4. Make sure your plugin project is set to build

5. Click Close to close the Configuration Manager

6. Adding a Plugin class

Next you'll want to add a Plugin class. This is a class that inherits from PluginBase. To do this:

1. Right-click on your project

2. Select "Add->Class..."

3. Name your class "MyPlugin" or whatever you want your plugin to be called

4. Add the following using:

5. Modify your plugin so it's public and inherits from PluginBase:

6. Add the following implementation into your plugin class:

        public override string FriendlyName
        {
            get { return "My Plugin Name"; }
        }

        public override Version Version
        {
            get { return new Version(0, 0, 0, 0); }
        }

        public override void StartUp()
        {
            // Add startup logic here:
        }

        public override bool ShutDown(Gum.Plugins.PluginShutDownReason shutDownReason)
        {
            return true;
        }

Getting your plugin into Gum

Now that you have a simple plugin, you need to do two things to test this plugin out. The first is to mark the plugin as a class that is exported using Microsoft Extension Framework. To do this:

1. Right-click on your project's References item in the Solution Explorer

2. Select "Add Reference..."

3. Click the "Assemblies->Framework" tab

4. Check "System.ComponentModel.Composition"

5. Click OK

6. Add the following using statement to your plugin class: using System.ComponentModel.Composition;

7. Modify your class definition so it looks like this (we're making it public and also adding the Export attribute:

  [Export(typeof(PluginBase))](Export(typeof(PluginBase)))
  public class MyPlugin : PluginBase

Now you can right-click on your project and select Build and it will generate a .dll for your project. This .dll file needs to be in the Plugins folder under the Gum binary. That is, from the location of your .sln file, you can go to . Once there, you will need to create a folder for your plugin (like MyPlugin) and place your .dll there.

To verify that your plugin is working correctly:

1. Run Gum

2. Click Plugins->"Manage Plugins"

Troubleshooting

The type or namespace name 'PluginBase' could not be found

This may happen if you are targeting different versions of the .NET framework. At the time of this writing Gum targets .NET 4.5. Therefore, you'll want to make sure that your Plugin project also targets .NET 4.5. To do this:

1. Right-click on your project

2. Select "Properties"

3. Select the "Application" tab

4. Verify that the "Target Framework:" is set to .NET Framework 4.5 (or whatever version Gum is currently on)

Subsections

• Setting Up Post Build Events

• PluginBase.AddAndRemoveVariablesForType

• PluginBase.AddMenuItem

• PluginBase.Export

Introduction

The AddMenuItem function allows adding menu items to Gum. The AddMenuItem accepts an enumerable of strings which allow you to embed menu items under a root menu item.

Code Example

The following shows how to create a menu item called "My Plugin" which contains two items: First and Second. Clicking each item results in a message box appearing. Add the following to your plugin's StartUp function.

// Add startup logic here:
var firstMenuItem = 
    AddMenuItem(new List<string> { "My Plugin", "First" });

firstMenuItem.Click += (args, sender) => 
    System.Windows.Forms.MessageBox.Show("You clicked first");

var secondMenuItem =
    AddMenuItem(new List<string> { "My Plugin", "Second" });

secondMenuItem.Click += (args, sender) =>
    System.Windows.Forms.MessageBox.Show("You clicked second");

Introduction

dll files created for plugins are files which are not required for Gum to function. In other words, if the file is there Gum will use it. If not, Gum can operate normally. This means that in your Visual Studio solution the project that you have created to hold your plugin will not automatically be copied to the build output folder. Fortunately Visual Studio supports post-build events which allow you to copy the built .dll to the plugins folder.

Creating a post-build event

To access the post build event on a project:

1. Right-click on your project in the Solution Explorer

2. Select "Properties"

3. Select the "Build Events" tab on the properties page

4. Notice the "Post-build event command line:" section

To add a post build event, you will need to add command line commands to copy the .dll and .pdb to the plugin folder. Post-build events are simply run in a command line environment after the build succeeds. Therefore you can put any logic in here, including running other .exe or .bat files.

For this example we will assume that the project is called PluginProject. You will want to change the following text to match your project's name. To copy the files, paste (and modify) the following:

if not exist $(SolutionDir)Gum\bin\Debug\Data\Plugins\ md $(SolutionDir)Gum\bin\Debug\Data\Plugins\
if not exist $(SolutionDir)Gum\bin\Debug\Data\Plugins\PluginProject\ md $(SolutionDir)Gum\bin\Debug\Data\Plugins\PluginProject\
copy $(TargetDir)PluginProject.dll $(SolutionDir)Gum\bin\Debug\Data\Plugins\PluginProject\PluginProject.dll
copy $(TargetDir)PluginProject.pdb $(SolutionDir)Gum\bin\Debug\Data\Plugins\PluginProject\PluginProject.pdb

Notice that "PluginProject" appears 8 times in the text above, so be sure to replace all instances with your project name.

Why do we include the .pdb file?

The copy script copies the .pdb file to allow you to debug your plugin. Specifically the PDB enables breakpoints to trigger and to break on exceptions.