Posting Events

In this tutorial, we'll explore two methods for posting Wwise events in Godot: using the AkEvent nodes provided by the integration plugin and writing GDScript code.

Adding a Listener to the scene tree

Before posting any events, it's essential to incorporate a listener into the scene. Achieve this by integrating an AkListener3D or AkListener2D node within the scene tree:

As an alternative, you can register a listener via GDScript:

extends Node3D


func _enter_tree():
	Wwise.register_listener(self)
	

func _process(delta):
	Wwise.set_3d_position(self, get_global_transform())

Should you opt for the custom nodes, the listener's position is automatically set every frame. For the manual approach, call Wwise.set_3d_position to set the listener's position.

Posting Events with the AkEvent Nodes

To play events using the AkEvent node, follow these steps:

1. Add an AkEvent3D or AkEvent2D node to the scene tree:

2. Click on the AkEvent node to access various settings in the inspector that can influence event playback:

• Event: Select the desired event from a list of available events.
• Trigger On and Stop On: Choose when the event should be posted and stopped (e.g., Enter Tree, Ready, Exit Tree).
• Stop Fade Time: Set the duration in milliseconds for the event fade-out when stopped.
• Interpolation Mode: Define the curve used for the fade-out.
• Is Environment Aware: Activate this option if the event should be assigned to the specified aux bus when the corresponding AkEnvironment node is active.

Select the desired event and trigger on callback. Try posting an event by playing the scene. Don't forget to load your banks and add an AkListener node to the tree.

Using Callbacks with the AkEvent Node

Callbacks in AkEvent nodes are exposed as signals. To connect a signal to a receiving node, follow these steps:

1. Identify the desired signal in the AkEvent node:

2. Connect the signal to the receiving node:

3. Godot will automatically create a function in the receiving node's script:

In this example, the dictionary containing information about the callback is printed. The output will look like this:

{ "callback_type": 512, "gameObjID": 27632075945, "musicSyncType": 512, "playingID": 1, "pszUserCueName": "", "segmentInfo": { "fBarDuration": 2.20191669464111, "fBeatDuration": 0.55047917366028, "fGridDuration": 8.80735397338867, "fGridOffset": 0, "iActiveDuration": 35229, "iCurrentPosition": 0, "iPostExitDuration": 0, "iPreEntryDuration": 0, "iRemainingLookAheadTime": 0 } }

Posting Events with GDScript

To post events using GDScript, follow these steps:

1. Register a game object using register_game_obj on the Wwise singleton. This function expects an object and a string defining the game object's name. You can pass "self" as the object, or define any other node as a game object. For more information about game objects, refer to the Audiokinetic documentation.

2. Call post_event or post_event_id on the Wwise singleton to post an event. Pass the name or ID of the event and the game object on which the event should be posted.

Example using post_event:

func _ready():
        # Make sure you have registered a Listener
	Wwise.register_game_obj(self, "Game Object Name")
	Wwise.post_event("Music", self)

Example using post_event_id:

func _ready():
        # Make sure you have registered a Listener
	Wwise.register_game_obj(self, "Game Object Name")
	Wwise.post_event_id(AK.EVENTS.MUSIC, self)

3. To use event callbacks, create a CookieWrapper object and a Callable. Assign the callable to the cookie property of the wrapper. Call the desired post_event callback function (post_event_callback or post_event_id_callback), passing the name or ID of the event, the desired callback flag, the game object, and the CookieWrapper object.

Example using post_event_id_callback:

extends Node3D

var cookie_wrapper:CookieWrapper = CookieWrapper.new()
var callable:Callable = Callable(self, "_event_callback")

func _ready():
	cookie_wrapper.cookie = callable
	Wwise.register_game_obj(self, "Game Object Name")
	Wwise.post_event_id_callback(AK.EVENTS.MUSIC, AkUtils.AK_MUSIC_SYNC_BEAT, self, cookie_wrapper)
	
func _event_callback(data):
        # Callbacks are done from the sound engine's main thread. 
        # Gather all the information you need and return immediately.
	Thread.set_thread_safety_checks_enabled(false)
	print(data)

You can find the callback flags constants in the AkUtils helper singleton.

Stopping Events

To stop an event, call stop_event on the Wwise singleton. The function expects the playing ID of the event, the fade-out time in milliseconds, and the interpolation mode for the fade-out. You can find the interpolation modes in the AkUtils helper singleton. The playing ID of the event is returned by the post_event functions.

Example:

var playing_id = Wwise.post_event_id(AK.EVENTS.MUSIC, self)
Wwise.stop_event(playing_id, 2000, AkUtils.AK_CURVE_LINEAR)

Handling Errors

If an error occurs while posting an event, Godot will print an error message in the error dock, providing information about the nature of the error. Here is an example of such an error message:

E 0:00:00:0581   script.gd:9 @ _enter_tree(): [AK_InvalidID]: post_event in src/wwise_gdnative.cpp:548

By examining this error message, you can gain insight into the specific issue that occurred.