8. Adding Code to Gum Objects

Introduction

Although Gum provides extensive layout control, many games require Gum components with custom logic. For example, a button may need to play a sound effect when clicked – logic which should be centralised in the button component code rather than added as events on every button instance.

This tutorial shows how to use partial classes to add custom logic to a button. Although we use partial classes for the specific functionality of adding sound effects, partial classes can be used for any other logic.

What is a Partial Class?

Partial classes, which use the partial keyword, allow the definition of a single class to be spread out across multiple files. Glue uses partial classes to separate custom code from generated code (so that generated code does not overwrite custom code). In fact, all screens and entities in a Glue project already use partial classes. You can see this by expanding any screen or entity in your project in Visual Studio.

The following image shows a GameScreen’s custom code:

The following image shows a GameScreen’s generated code:

Adding a Partial Class File

All Gum components and screens are generated as partial files (they include the partial keyword) so we don’t need to make any changes in Glue or Gum to enable adding additional partial class files.

All Gum runtime object code is contained in the GumRuntimes folder. By default, this contains only generated code files, but we can add our own custom code here.

To add a partial file:

  1. Locate the GumRuntimes folder in Visual Studio’s Solution Explorer

  2. Right-click on the GumRuntimes folder
  3. Select Add -> Class…
  4. Enter the name matching the desired screen or component. For this tutorial we’ll add a partial for the Button component, so we’ll enter the name ButtonRuntime.

  5. By default, Visual Studio will assign a namespace to your newly-created class, which should be <YourProjectNamespace>.GumRuntimes . Verify that this is the case, as the namespace of your newly-created file must match the namespace of the generated file.
  6. Add the partial keyword in front of the class keyword in the newly-created file

  7. Save the project (ctrl+shift+s) so that Glue is notified of the changed project file. You can verify that the project has been saved and Glue reloaded the project if you are notified by Visual Studio that the project has changed.

  8. Click Reload. This will embed the ButtonRuntime.Generated.cs file under the newly-created ButtonRuntime.cs file.

Adding CustomInitialize

Gum runtime objects all support a CustomInitialize call. Usually, CustomInitialize is where internal event handlers are added. To add CustomInitialize, add the following code inside the ButtonRuntime.cs file:

We can handle the Click event by modifying the ButtonRuntime code as follows:

Now we can add code in our HandleClick method to perform any custom logic when the user clicks the button. This code will be executed on every instance of ButtonRuntime across our entire project.

Troubleshooting

No defining declaration found for implementing declaration of partial method

This is usually caused by having a mismatched namespace in your partial compared to the partial of the generated code.

<- 7. States — Back to Tutorials ->