As you continue working on your game, you may notice that several scenes have a lot of scripts in common. Perhaps you run events setting a player’s sprite sheet and coordinates at the start of a new area, attach the same actions to your buttons, or a series of events to give out rewards after a battle. When you run into these situations, you probably find yourself copying and pasting the same events over and over again. Sure, placing them in an event group makes the cloning between actors/triggers/scenes more manageable – but when you need to make a bug fix or optimize a sequence, you’ll find yourself losing time tracking down each copied and pasted script.
Luckily, there’s an event type to make repeating scripts much easier: Custom Events!
What Are Custom Events?
Custom Events are groups of events that you can create and add to your actor, trigger, and scene scripts just like normal events. The trick is that unlike the other standard events in GB Studio, you define what a custom event does. Once you’ve created a custom event, you can re-use that script multiple times, and whenever you make a change to a custom event, it will update for each occurrence across your game. Custom Events make managing repeated sequences much easier, as you only need to look in one place to test, edit, or fix a bug.
If you’re creating the scripts anyway, how is this any different from simply creating the scripts directly in the actor/trigger/scene? While a Custom Event’s biggest advantage is its ease of editing, there are some other uses. Let’s dive into our first example to show what can be done.
Building a Custom Event
For our first example, we’ll build a custom event to replace a feature that has been “removed” from later versions of GB Studio. With the release of the 2.0 Beta, Actors no longer have a Movement Type, which removed the frequently used “random walk” option. Since that change, creating a randomly walking NPC or Enemy now takes a Math Event, A Switch, and several Move Relatives in an Actor’s “On Update’ tab. Sure, it’s not the longest script, but it’s also unlikely to change for each NPC you’re using it in. This makes it a perfect candidate for a custom event. Instead of Copying and Pasting those events into another actor (or even cloning the actor altogether), we can create a “Move Randomly” custom event that will be called from the search list whenever we need to make an NPC move randomly.
To start, navigate to your Custom Events section. In Beta 5, you can find Custom Events via the Navigator (on the left side). If you’ve hidden this, you can go to View > Show Navigator to bring it back. If you’re on earlier versions, Custom Events appear when you click the background of the Game World (similar to how you view a player actor’s settings). Custom Events can be given a name, and also a description that can be used as a reminder of what the event does.
Once created, you’ll notice that the custom event field looks just like any other script. The major difference is when you add your events, variables and actors do not reference any that have been placed in your game. Instead, custom events use placeholder values, labeled alphabetically from A to J.
A single Custom Event can have up to 10 variable and 10 actor placeholders. When an event is added to a custom event’s script, you can select which placeholder to reference. These placeholders can be renamed, and once that Custom Event is added to a scene, event or actor, then the actual variable or actor you wish to use can be assigned to that placeholder.
To continue our example, let’s create that Walk Randomly custom event. Create a new Custom Event, and name it “Walk Randomly”. In its script, add a [Variable: Math Functions] event. Select Variable A, and then have it set to a random number between 1-4. Then, add a switch, and set it to check variable A. In each of it’s “When” sections, add a move relative in a different direction with collisions enabled for “Actor A”.
In your scene, create a few actors, and then in their “On Update” field, add an event and search for “Walk Randomly” – you should see your custom event listed. When you add a custom event, it has a list of each placeholder variable. For this event, you should see a Variable A placeholder and an Actor A placeholder. Assign the variable to Local 0, and the actor to “Self” (these should be the default anyway). Do this for each actor in your scene, and then test out your game.
Oh no! They’re moving much too fast. We’ll need to make a change. Go back to your custom event’s script, and place a “Wait” event at the end of it (a few seconds should do). Now, when you test your game, the change should be reflected for all actors that were using that custom event.
Limitations
Custom Events are an excellent way to optimize your game when you find yourself repeating scripts. The quality of life they add to bug fixing and editing scripts across scenes is unmatched, but they do have their limitations. Due to their limit of referencing 10 variables and actors, larger scripts (for example, being used in rpg battle systems) may need to be split across multiple custom events. You also need to make sure you’re properly re-assigning the placeholder variables and actors once you add your custom event to an actor/scene/trigger. While they do improve the QA process for scripting, they have their own areas that will need to be reviewed for mistakes when adding them to scripts.
Other Common Uses
This article covered how to use a custom event to replace a feature that is commonly used across game types, but there is no way to know exactly what scripts are being repeated in your game and how converting to custom events could help you in your development. In my own experience, I’ve had success with custom events being used to handle:
Button Assignment: attaching scripts to customize button mappings (like weapons, jumps, start menus, etc) can be handled via a custom event that is run at the start of every scene.
Managing Money: when working with variables over 255, running the scripts to pass values back and forth between your ones/tens/hundreds columns can be quickly referenced in a custom event, reducing your script complexity
Changing a player sprite sheet: if you have a character customization or use 4-frame animations, custom events can be called at the start of the scene or on update to make sure you’re always using the correct sprite sheet.
Controlling Random Encounters, Puzzle Rocks, or other common elements of a dungeon in an RPG.
Updating HUD variables and displaying actors in an RPG battle system.
Friendly Neighborhood Game Designer (he/him)
GB Studio Games | Tabletop Games
