Sparen's Danmakufu ph3 Tutorials Lesson 26 - Utilizing EV_USER with NotifyEventAll

Part 1: What will be covered in this lesson?

Continuing on from the previous tutorial, we will now cover user events and NotifyEventAll as a means for triggering these user created events. As this lesson is a continuation of the previous, it is highly recommended that you be familiar with Events in general before moving on to this lesson.

Part 2: What are User Events?

In the previous lesson, we covered Events in general, and how they are used in Danmakufu as well as how a scripter can execute code when a built-in event fires in Danmakufu.

User Events are custom events that can be created by a scripter to fire whenever they want, and form the basis of most communication between Single Scripts, Stage Scripts, and Package Scripts. The number of uses available for User Events is essentially limitless - the most common uses are for spawning items, handling sound effects, and handling effects such as boss explosions which typically are not run inside a Single script due to them being performed after the boss battle has concluded (some scripters use a dummy single script with just the explosion).

User Events come in a variety of flavors - EV_USER (1000000), EV_USER_SYSTEM (2000000), EV_USER_STAGE (3000000), EV_USER_PLAYER (4000000), and EV_USER_PACKAGE (5000000). Naturally, the different types are for different use cases.

Note that each event constant corresponds to a number - the constants are essentially shorthand. So there are 1 million different possibilities for each category. For example:

@Event {
        alternative(GetEventType)
        case(EV_USER_PLAYER) { }
        case(EV_USER_PLAYER + 1) { }
        case(EV_USER_PLAYER + 2) { }
        // ... ... ...
}

Do note that not all of these constants will be available at any given time - in a package, you may not be able to access EV_USER_PLAYER, for example. That being said, you will not be running out of possible events any time soon.

Part 3: How do I use NotifyEvent?

Now, to use these custom events you must be able to call them somehow, as they are never triggered automatically. Triggering is done via NotifyEvent() or NotifyEventAll() - for all practical purposes NotifyEvent() is never used, as it requires the script ID. NotifyEventAll will hit every currently running script and if they have the given event in their @Event, the code will execute. This does mean that if you accidentally use the same event constant for two different things in two different places, both will get called, so be careful not to reuse event constants for different events.

NotifyEventAll() has a number of interesting features. First it takes the event type/constant (I.E. EV_USER_STAGE + 12) and then it takes parameters. Here is where it gets interesting.

Say we want to spawn a boss explosion in the Stage script at the boss's position. In the Single script, before deleting the boss in our cleanup task (e.g. TFinalize), we can do the following:

NotifyEventAll(EV_USER_STAGE+777, [ObjMove_GetX(objBoss), ObjMove_GetY(objBoss)]);

In the slot reserved for a single argument, we can pass an array of multiple values! Just be aware that arrays in Danmakufu can only hold a single type (i.e. only numbers or only strings), so if you want to pass types of different values, you will need to convert to a String and then parse afterwards.

Speaking of that afterwards, what goes in @Event for our stage script?

    case(EV_USER_STAGE+777){ //Boss Explosion
        let arg = GetEventArgument(0); //x, y
        BossExplosion(arg[0], arg[1]);
    }

As you can see above, we use GetEventArgument(0) to retrieve the argument passed in NotifyEventAll(). This array can then be indexed to retrieve the boss's coordinates.

There are many ways to use User Events - we will discuss Items and some other interesting features in following lessons.

Quiz: User Events

1) In large projects, it is often inconvenient to load and play sound effects in each and every single script, as there are many sound effects that are inevitably left but not used, and there is a lot of code duplication. In this scenario, which of the following EV_USER categories are well-suited to handling sound effects in a stage script?

A. EV_USER_PLAYER
B. EV_USER_PACKAGE
C. EV_USER

Summary

• Custom User Events that can be triggered by the user are provided by Danmakufu
• NotifyEvent and NotifyEventAll can be used to trigger User Events
• User Event constant IDs provide at least 1 million options per category

Sources and External Resources

Miransu's EV USER Guide (Miransu)
-->An older guide on getting started with User Events.