© vrchewal
Announcer Manager
version 1.0 for Unity
Product Page: vrchewal.com/unity/announcer-manager
Documentation: View Online
Asset Store: http://u3d.as/17vP
Pack Guide: View Online
Support: support@vrchewal.com
Jump To:
Introduction
In every game, there are key moments that deserve to be highlighted for the player. Nothing puts the exclamation on these moments better than an announcement. You have likely already experienced this in games like CounterStrike, Portal, Dota 2, etc. The Announcer Manager adds a dimension to the game that can elevate the player’s experience.
An announcement is simply an audio file. The Announcer Manager manages announcements via events. Events can be any moment in the game such as a headshot in an FPS, the arrival of the mega boss or as simple as starting the game.
Events are organized in packs. A pack is generally a group of events organized by a theme. For example, you could create packs for male, female and alien voices that are used based on player choices. You can create packs for your own games and buy/sell packs in the asset store.
Which events in your game deserve to be announced?
Structure and Terms
The Announcer Manager is best organized with a structure of Announcer → Pack → Event → Announcement for easiest viewing and organization. It is recommended that you stick with this structure until you become more familiar with the system and its API. When you become an expert, the structure becomes more flexible.
Announcer → Pack → → Event → → → Announcement → → Event → → → Announcement → → → Announcement |
Announcer
The main script that holds the API for playing events and contains the global settings. For more details, see the Announcer section.
Pack
A collection of events that can be packaged and grouped as a themed pack. Only one pack can be active in the Announcer Manager, but multiple can be present and switched at run time. A Default Pack can be selected to act as a fallback in case the active pack does not contain the triggered event. For more details, see the Pack section.
Event
An event represents a single moment in the game such as the start of a round, capture of the flag or headshot. The event script allows for many ways to select announcements. For more details, see the Event section.
Announcement
An individual audio file played for an event. Multiple announcements can be available for each event giving diversity of the announcements. For more details, see the Announcement section.
Quick Start
Let’s get you going as quick as possible with the Announcer Manager. In a few steps, you should be up and running with your first announcement.
1 | Create an empty object in the hierarchy, rename it Announcer and add the Announcer script.
|
2 | Drop in the SamplePack prefab as a child of the Announcer (/Announcer Manager/Packs/SamplePack) |
3 | In the Start() method of any script, add Announcer.PlayEvent(“StartLevel”); and using AnnouncerManager; at the top of the script. |
4 | Congratulations! You just setup your first event! Play the scene and listen for the announcement to confirm everything is working. |
Look at the list of events in the SamplePack to find events that match events in your game. Add the PlayEvent method to your code for each event in their originating scripts. See the next section (From Scratch) to see how to create your own Packs, Events and Announcements from scratch. See the Examples section for a review of the example scripts located in the /Announcer Manager/Examples folder for additional API methods.
From Scratch
1 | Create an empty object in the hierarchy, rename it Announcer and add the Announcer script.
|
2 | Create a new empty object as a child of the Announcer, rename it Pack and add the Pack script.
|
3 | Create a new empty object as a child of Pack, rename it StartLevel and add the Event script.
|
4 | Create a new empty object as a child of StartLevel, rename it begin_01 and add the Announcement script.
|
5 | Find the “SamplePack_StartLevel” audio file within the SamplePack Audio folder and drag it onto the Audio Clip box within the inspector for the begin_01 announcement.
|
6 | Create a new empty object, name it whatever you want and add a new C# script. Open the script, add using AnnouncerManager; to the top of the script and Announcer.PlayEvent(“StartLevel”); to the Start method of the script.
|
7 | Congratulations! You have just created your first announcement from scratch! Hit the play button to start the game and listen for the StartLevel announcement. Now you can add more events and announcements to this pack or create entirely new packs. Grab your microphone and start announcing!!! |
There are additional code examples in the /Announcer Manager/Examples folder. It is highly recommended that you review each of the examples to learn more about the Announcer Manager API.
________________________________________________________________________________________
Examples
There are a couple example scenes and scripts to help you get started. Example1 shows how to use the system for regular use. If you only have one pack, everything you need for code is found in this example. If you have multiple packs or want to deviate from the suggested methodology, you should review Example2 for additional API methods. Example3 demonstrates the AutoPlayEvent script for a no-code approach.
You can find all of the examples in the /Assets/Announcer Manager/Examples folder.
________________________________________________________________________________________
API
The following methods are open via the Announcer API.
________________________________________________________________________________________
The Scripts
The following four sections will go into detail on each of the main scripts of the Announcer Manager. This will help you better understand what each script is doing and how they interact with each other.
Announcer
The Announcer is the main script of the system and is setup as a singleton (there can only be one in the scene). It is the gateway into the API. It is recommended to add it to the Script Execution Order list to ensure Unity runs this script earlier than the other scripts (see Troubleshooting #1). Though this is not required, it will reduce the warnings in the Console due to Unity randomly choosing which game objects to Awake first.
The Debug Text box in the Inspector will show some useful information about the state of the Announcer if you have Console turned on. This is especially helpful with debugging to see which event was the last played.
Properties
Audio Source | AudioSource component to play announcements. See Also: HasAudioSource, SetAudioSource, Unity Audio Source |
Active Pack | The current pack used by the Announcer for event selection. See Also: ActivatePack, CanPackActivate, SetPackCanActivate, HasActivePack |
Default Pack | The fallback pack used by the Announcer if the active pack is missing the targeted event. See Also: SetDefaultPack, HasDefaultPack |
Auto Activate Pack | Activates the first valid pack that registers with Announcer. See Also: RegisterPack |
Console | Sends useful debug information to the console and additional information to the Debug Text box in the Announcer inspector. |
Pack
The Pack is a collection of events. If you only need a single pack in your game, the default settings will work for your needs. However, you may choose to include multiple packs in the game. This opens up several options for you and the player.
Packs are not required to have identical events or same number of announcements. Each is their own island. If you play an event that is not found in the active pack, the Announcer will attempt to find the event in the default pack. If not found in the default pack, it will simply ignore the request.
Let’s look at a couple scenarios for a better understanding of pack use and flexibility.
Scenario 1: You allow the player to choose a character class and each has their own voice. You can create a pack for each class so that events in the game are announced in the character’s own voice. A pack should be created for each class with the same events. At runtime, you check for the player class and set the active pack using the ActivatePack method of the API. In addition, if you have other voices for NPC characters that are not dependent on the player choice, you can setup another pack for those voices and make it the default pack. As long as the events played are not in the active pack, the default pack will be used to deliver the NPC events.
Scenario 2: You have a standard voice pack that comes free with the game and wish to offer additional voices to the player as DLC. The player buys a special voice pack for your game that has 80% of the events in your game. You may set the special DLC pack as the active pack and your standard pack as the default pack. Any event not found in the special packs will be handled by the standard pack.
Scenario 3: You buy several themed packs from the Asset Store and drop them in the Announcer hierarchy. You check the events list for each and realize many of events are not shared between the packs. Not to worry, you may play events at will and if present, the Announcer will play the event in the active or default packs.
Scenario 4: You have environmental audio to play based on the player’s position on the map or at random. For example, birds chirping or a lion’s roar. You can add those environmental sounds to the default pack and play them at random intervals with the AutoPlayEvent script. The Announcer plays any audio clip, you are not restricted to just voices!
If you are a voice artist and wish to create packs for sale on the Unity Asset Store, please contact us at vendors@vrchewal.com for more information.
Properties
Can Activate | If true (checked), the Pack can be activated as the Active Pack. See Also: ActivatePack, CanPackActivate, SetPackCanActivate |
Event
The Event is a collection of announcements. The Event name is what you will use the play the announcements via the PlayEvent method of the API. Events have several ways of choosing which announcement to play. You can also control how the event manages itself.
You can add multiple announcements per event. This will add greater diversity of experience for the player if you offer multiple “takes” per event. For example, if the player is taking damage from the enemy you might want to have an event named “TakingDamage” You might also want to have multiple ways to notify the player of this like the following: “We are taking damage!”, “We are under attack!”, “Ouch, ouch!” or “Commander, we can’t defend against this heavy bombardment much longer!”
Properties
Active | If true (checked), the Event can be played via the API.. See Also: ActivateEvent, DeactivateEvent |
Single Use | If true (checked), the Event will auto deactivate after the event is played. Can be reactivated later via the API. This is great for ensuring one time events only can be played once. See Also: SetSingleUse |
Replay Delay | Sets the delay for an event to play again after the event is played. See Also: SetReplayDelay |
How to Select | The method by which the Event selects announcements. If there are multiple announcements under the Event, you can set how the Event chooses which announcement to play. Random: A random announcement will be chosen each time the event is played. Sequential: Will choose the announcements in order from first to last. Least Used: The least used announcement will be selected. Works like sequential if more than one announcement is the least used. Weighted: Each announcement can have a weight value set (1-10). This works like a lottery where each announcement has a number of tickets equal to the weight set. A random number is selected and the winning ticket gets selected. The higher the weight, the more likely the announcement will be selected. See Also: SetHowToSelect, SetAnnouncementWeight |
Chance to Select | The percentage chance an announcement will be selected by the event. If set to 100, an announcement will be selected every time the event is played according to the How to Select field. If less than 100, there is a chance no announcement will be selected when the event is played. This is useful if you want to introduce some randomness to the announcement playing for each time the event occurs. See Also: SetChanceToSelect |
Announcement
The Announcement is the script that contains the audio clip to play for the event. There will be one announcement for every audio file you want to play. Each announcement should have its own game object.
Properties
Audio Clip | The Audio Clip (audio file reference) to play when triggered. Use the inspector to drag an audio file into the Audio Clip field to assign. See Also: Unity Audio Clip |
Active | If true (checked), the Announcement can be selected by an Event to play the Audio Clip. See Also: ActivateAnnouncement, DeactivateAnnouncement |
Weight | Each announcement can have a weight value set (1-10). The higher the weight, the more likely the announcement will be selected. Only applicable if the Event set the How to Select field to Weighted. See Also: SetAnnouncementWeight, How To Select |
AutoPlayEvent
The AutoPlayEvent script allows for a no-code approach to playing events. The AutoPlayEvent script will play the event connected on its same gameobject. You will first choose the method for the autoplay. The default is Conditional, which allows you to select a gameobject and define the variable you wish to check every update. The other methods allow you to play events based on Unity callback functions or random intervals.
The AutoPlayEvent script will run on every update and check for your conditions. It will attempt to play the event each and every frame where the conditions match. It is advised that you apply the appropriate event settings on the event script to ensure the event only plays as much as you want.
Properties
Method | The method the script will use to play the event. Conditional: Allows you to set conditions (gameobject variables) for evaluation every frame to determine when to play the event. Interval: Allows you to set a minimum and maximum random time interval to play the event. Good for a hands off approach to autoplaying events based on time. All other options are Unity MonoBehavior callbacks and will run according to the gameobject execution order. |
Conditions | |
| The game object that contains the variable to monitor. |
| The component that contains the variable to monitor. |
| The variable within the game object and component to monitor. |
| The comparison operators to evaluate the value against the variable. |
| The value to compare against the variable. |
Settings | |
| After playing the event, the script will remove itself from the game object if single use is checked. |
| Will play this event on whatever AudioSource you input. Leave empty to use the default Audio Source set in the Announcer script. |
Announcement Notification
You can receive a notification every time the manager plays an announcement. Subscribe to the Announcer delegate to receive data on every announcement made by the manager. Your method must include a single parameter with the type of AnnouncementData. See the examples and data structure below.
Methods
SubscribeNotification void | Announcer.SubscribeNotification(EventNotification method); Subscribe to receive notifications every time the manager plays an announcement. You must create a method in your script that accepts a single AnnouncementData parameter. An example: public void AnnouncementNotification(AnnouncementData data){ Debug.Log(data.Event.name); } private void OnEnable(){ Announcer.SubscribeNotification(AnnouncementNotification); } private void OnDisable(){ Announcer.UnsubscribeNotification(AnnouncementNotification); } |
UnsubscribeNotification void | Announcer.UnsubscribeNotification(EventNotification method); Unsubscribes from the delegate to receive notifications. This keeps memory issues and errors from cropping up. See above for example. |
The AnnouncementData class is passed as a parameter for the Announcement Notification. The structure of the AnnouncementData class is described below, but you can view the bottom of the Announcer.cs file to see the class directly. This class helps to see the information on the announcement that was just played and make adjustments to events or announcements if needed. It is recommended you use the Announcer API to make major adjustments though.
AnnouncementData
Announcement | The announcement that was played. A reference to the actual instance of the announcement. |
Event | The event that was triggered for the announcement. |
Pack | The pack that was used to play the announcement. |
time | When the announcement was played. Uses Unity Time.time. |
AudioSource | The audio source used to play the announcement. |
usedActivePack | Did the manager use the Active pack to play this announcement. A bool that returns true if yes, or false if the Default pack was used. |
Troubleshooting
Oops, something went wrong. You have come to the right place.
1 | Problem You see warnings in the Console with the following: You are trying to create a MonoBehaviour using the 'new' keyword. This is not allowed. MonoBehaviours can only be added using AddComponent(). Alternatively, your script can inherit from ScriptableObject or no base class at all UnityEngine.MonoBehaviour:.ctor() Answer Open the Script Execution Order (Edit → Project Settings → Script Execution Order). Add AnnouncerManager.Announcer with a value of -1 and hit apply. |
2 | Problem You see the following error in the Console: The name ‘Announcer’ does not exist in the current context. Answer Add using AnnouncerManager; to the top of the script with the error. |
Support
Please go through the From Scratch section and then the Troubleshooting section to see if your question is answered first. If not, feel free to ask your question on the Forum. You can also get your question answered by emailing support@vrchewal.com
Voice artists that wish to create packs for sale on the Unity Asset Store should contact us at vendors@vrchewal.com.
Thank you for your purchase of the Announcer Manager!