Essentials Series/Dispatchers

This page is part of the Essential Series modding tutorials. In this guide, you will learn how to use DPAT assets. Dispatchers are the most basic base asset type. Their only function is to send and receive events, and do nothing other than that.

Using a Dispatcher
Industrial Park has a Dispatcher template. Dispatchers have no unique fields, only all of those present in Base assets, including Links. Dispatchers can be used to help with all kinds of game logic, below are some common examples, but other use cases exist.

ScenePrepare
Every base asset receives ScenePrepare when a level starts. If you want an Entity asset to be set to invisble when the level starts, you can create a dispatcher and add ScenePrepare => Invisible with the target asset as the object to its links (although there are more elegant ways to do this).

Persistent Setups
Persistent assets are saved to the game's save file, and keep their state through loads. Let's say you place a Spatula on your level, and it is on a floating platform. You don't want the floating platform to appear anymore after the spatula has been collected. This can be done with a dispatcher: This setup means that, once the spatula is collected, it will enable a previously disabled dispatcher. Since the dispatcher is persistent, it will be enabled forever, even after player death and scene reload. The enabled dispatcher will send CollisionVisibleOff to the platform on ScenePrepare, meaning the platform will not appear anymore.
 * 1) Create a dispatcher and add ScenePrepare => CollisionVisibleOff with the platform as the target asset to its links.
 * 2) Set EnabledOnStart to false (this will cause the asset to start disabled, meaning it will not send or receive any events) on the dispatcher.
 * 3) Set StateIsPersistent to true on the dispatcher.
 * 4) Add a link to the Spatula: Pickup => Enable, with the dispatcher as the target asset.

All Base assets can be set as persistent or not, enabled on start or not. This type of setup is used in many different points of the game. For example, when you first meet an enemy, a cutscene plays. At this point, a persistent dispatcher with a link that disables the cutscene trigger is enabled, so it will never play again.

Relayers
Let's say you have four different buttons on your level, and you want all of them to do the same thing when pressed. But this thing involves 14 different events, and if you change it on one button, you have to change it on all of them! Instead of having a copy of all links on each button, you can put the links in a dispatcher. The buttons will have only one link, ButtonPress => Run with the dispatcher as the target asset, while the other 14 are on the dispatcher itself, with Run as the receiving event. The dispatcher will simply relay the events it receives. (note that Run is just an example; you could use any other event, actually).

PlayMusic
If you want a music track to play, you can send the PlayMusic event to any dispatcher with the number of the song on the first argument (the game always uses a dispatcher called MUSIC_DISP, and so can you if you wish, but it's not necessary). Note that this cannot be done on ScenePrepare, as you have to wait at least one frame before PlayMusic actually works. An alternative way is to make a timer that runs on ScenePrepare and expires in 0.1 seconds before sending PlayMusic to a dispatcher on Expired. These are the possible values for the argument:
 * 00 - Bikini Bototm
 * 01 - Jellyfish Fields
 * 02 - Downtown Bikini Bottom
 * 03 - Goo Lagoon
 * 04 - Poseidome
 * 05 - Rock Bottom
 * 06 - Mermalair
 * 07 - Silence (Sand Mountain has no unique track!)
 * 08 - Industrial Park
 * 09 - Kelp Forest
 * 10 - Flying Dutchman Graveyard
 * 11 - SpongeBob's Dream
 * 12 - Chum Bucket Lab
 * 15 - Slide
 * 16 - Ambush

More information about custom music can be found in the Sound Effects page.