IO's & Categories

A NotifyIO is a method of displaying notifications to the player. Here's a demo video showing an example configuration of all NotifyIO's:

Sounds in Notifications

All NotifyIO's support any setting from the SoundIO type. Therefore, you can play a sound whenever a notification is shown. (1)

1. In other words, every NotifyIO also supports every option from SoundIO.

Most NotifyIO's have unique settings that somehow change how a notification is displayed. The actual message is either defined in the event that triggers the NotifyIO or the appropriate language file in the lang directory for all built-in notifications.

Sending Notifications: notify

You can send notifications using the notify event. This is how to use it:

Warning

All colons (:) in the message part of the notification need to be escaped, including those inside variables. One backslash (\) is required when using no quoting at all (...) or single quotes ('...'). Two backslashes are required (\\) when using double quotes ("...").
You also need to escape the backslash itself, if you use double quotes for some things like \n.

Examples:
eventName: notify Peter:Heya %player%! eventName: notify Peter\:Heya %player%!
eventName: 'notify Peter:Heya %player%!' eventName: 'notify Peter\:Heya %player%!'
eventName: "notify Peter:Heya %player%!" eventName: "notify Peter\\:Heya %player%!"
otherEvent: notify You own %math.calc:5% fish! otherEvent: You own %math.calc\:5% fish!
newLine: "notify Some multiline \n message" newLine: "notify Some multiline \\n message"

Parameter	Syntax	Default Value	Explanation
message	Any text with spaces!		The message that will be displayed. Supports variables and translations. Must be first
category	category:info	None	Will load all settings from that Notification Category. Can be a comma-seperated list. The first existent category will be used.
io	io:bossbar	io:chat	Any NotifyIO Overrides the "category". settings.
any io specific settings	setting:value	None	Some notifyIO's provide specific settings. Can be used multiple times. Overrides the "category" settings.

Usage Examples

Check out the notify IO specific options if you haven't yet. You must understand these two if you want to use the Notify system to it's full extend. Advanced users may also use Notify Categories to make their lives easier.

#The simplest of all notify events. Just a chat message:
customEvent: "notify Hello %player%!"  

#It's the same as this one since 'chat' is the default IO.
theSame: "notify Hello %player%! io:chat"

#This one displays a title and a subtitle:
myTitle: "notify This is a title.\\nThis is a subtitle. io:title"

#Plays a sound:
mySound: "notify io:sound sound:x.y.z"

#This one explicitly defines an io (bossbar) and adds one bossbarIO option + one soundIO option:
myBar: "notify This is a custom message. io:bossbar barColor:red sound:block.anvil.use"

#Some events with categories.
myEvent1: "notify This is a custom message! category:info"
myEvent2: "notify This is a custom message! category:firstChoice,secondChoice"

#You can also override category settings:
myEvent3: "notify Another message! category:info io:advancement frame:challenge"

#Use multiple languages:
multilanguage: "notify {en} Hello english person! {de} Hello german person! {es} Hello spanish person!"

Translations

Notifications can be translated with this syntax:

example: "notify {en} ABC {de} DEF"

The value in {} is a language key from messages.yml. Any text after the language key until the next language key belongs to the specified language. There must be a space between the language key and the message. In this example, english users would see ABC and german ones would see DEF.

Broadcasts

persistent, static

You can broadcast notifications to all players on the server using the notifyall event. It works just like the notify event. Variables are resolved for each online player, not for the player the event is executed for.

Example

events:
  announceDungeon: "notifyall A new dungeon has opened!"

Available NotifyIOs

There are a bunch of notify IOs available. Below is a list of all available notifyIOs and their possible options.

Notify Syntax

events:
  notifyExample: notify <message> io:<NotifyIO_Type> <option_1>:<option_1_value> <option_2>:<option_2_value> 
    <category>:<category_Name>

Chat

Writes the notification in the player's chat.

Preview

Option	Description
Sound	Any option from the SoundIO.

Advancement

Shows the notification using an achievement popup.

Danger

Minecraft will always play the default advancement sound for this NotifyIO type. It's not possible to stop this sound from playing.

Workarounds

To stop this behaviour, you would have to override / remove that sound from your server's resource pack. You can still add your own additional sound as usual though. It will then be played together with the default advancement sound.

Preview

Option	Description
frame	What Achievement frame to use. Can be: challenge, goal, task
icon	What icon to show. Must be the vanilla name of an item. Example: minecraft:map
Sound	Any option from the SoundIO.

Actionbar

Shows the notification using the actionbar.

Preview

Option	Description
Sound	Any option from the SoundIO.

Bossbar

Shows the notification using a bossbar at the top of the players screen.

Preview

Option	Description
barFlags	What flags to add to the bossbar. PLAY_BOSS_MUSIC seems to be broken in either server or the game itself.
barColor	What color to draw the bar.
progress	What progress to show in the bar. A floating point number between 0.0 (empty) and 1.0 (full). Supports variables.
style	What bar style to use.
stay	How many ticks to keep the bar on screen. Defaults to 70. Supports variables.
countdown	Animates the progress of the bar if set. The value determines how often the bar is updated. Formula: \(TimeBetweenUpdates = \frac{stay}{countdown}\)
Sound	Any option from the SoundIO.

Title

Shows the notification using a title. A subtitle can be sent simultaneously by adding \n to the notification text. Anything after these characters will be shown in the subtitle.

Preview

Option	Description
fadeIn	Ticks to fade the title in. Default 10
stay	Ticks to keep title on screen. Default 70
fadeOut	Ticks to fade the title out. Default 20
Sound	Any option from the SoundIO.

SubTitle

Shows the notification using a subtitle.

Preview

Option	Description
fadeIn	Ticks to fade the title in. Default 10
stay	Ticks to keep title on screen. Default 70
fadeOut	Ticks to fade the title out. Default 20
Sound	Any option from the SoundIO.

Totem

Shows a totem with a "customModelData" NBT tag. This allows you to replace the totem with a custom texture or model during the animation.

Preview

Option	Description
customisation	This CustomModelData will be used.
Sound	Any option from the SoundIO.

Sound

This IO just plays a sound. You can use its options in any other IO. You should read the wiki page of the playsound command as Minecraft's sound system is kinda strange. Just one example: Sound never moves in Minecraft. It's totally static. Keep that in mind when creating sounds close to a player. They can move around the sound and make it louder or quieter by walking towards / away from it.

Option	Description
sound	Sound to play. If blank, no sound. Either vanilla Minecraft sounds (get them using /playsound autocompletion) or the name of a sound from a resource pack.
soundcategory	The category in which the sound will be played.
soundvolume	Minecraft's special sound volume. Default: 1
soundpitch	Pitch of the sound. Default: 1 Min: 0 Max: 2
soundlocation	Default: The player's location. A location using the BetonQuest ULF. Can include variables.
soundplayeroffset	This option is special. See below.

soundplayeroffset

soundplayeroffset is an option to move the location of the sound based off the player's location as well as the soundlocation option. This option can be a number or a vector. (1)

1. For more information about how BetonQuest processes location data, see Unified location formatting.

NumberVector

Example Usage

You could make a "sound compass" that will play a sound in the direction of a point of interest.

This is only useful if you set the soundlocation option to a location that isn't the player's. Using a number will move the "source" of the sound so that it "points" towards the soundlocation option relative to the player's current location using the value that you set as distance increments. The sound will be at the actual location if the player is closer to the soundlocation then the soundplayeroffset would allow. (1)

1. It can help to imagine it as a line of rope with knots spaced out equally stretched between the player's location and the soundlocation. The soundplayeroffset value determines the distance between the knots and will play sounds at those knots.

Visual Explanation

This shows how the sound will be played at the soundlocation if the soundplayeroffset is bigger then the current distance between the player and the soundlocation

Example Usage

A Halloween event where the player hears a whispering into his left ear, no matter where he is or how he turns his head... 🎃

A vector has to be in the format (x;y;z). This system will use the player's relative coordinate system. This means that the vectors' x-axis is left/right from the players head(1), the y-axis is up/down from the player's head location(2) and the z-axis is in-front/behind the player's head; it will move along the player's head(3).

1. Positive numbers are to the left of the player, negative numbers to the right.
2. Positive numbers are above the player's head, negative numbers are below.
3. Positive numbers are in-front of the player, negative numbers are behind.

Visual Explanation

In contrast to their global counterparts, relative x,y,z axes do not change their orientation relative to the player. Example: The positive x-axis will always point left from the perspective of the player.

Video Example

blue line = direction the player is looking in
🟢 = soundlocation argument
🔴 = the actual location the sound is played at
soundplayeroffset = (0,0,5)

The sound is always played 5 block away from the soundlocation. The direction is however based on where the player is looking.

Suppress

Does not output any sound or text 🔕. Can be used to remove built-in notifications.

Categories

Notify Categories are pre-defined NotifyIO settings. They can be applied to any notify event and are also used by BetonQuest's built-in notifications. All categories must be defined in a section called notifications.

Warning

A note about the notifications section: BetonQuest searches through all packages and just uses the first one it finds. Therefore, you should probably create just one notifications section. We will improve this in BQ 2.0.

Custom Categories

Tip

Categories are very useful for notifications that you are going to be sending players multiple times and want to create a unified, consistent look and sound.

Custom categories are user-created presets for any notify event. They shorten your events and enable you to change how a notification of a certain category looks in one central place. They do not allow you to set a message though as the message is an argument of the notify event!

Custom Categories Example Configuration

notifications:
  money: #(1)!
   io: advancement #(2)!
   icon: gold_ingot #(3)!
   sound: entity.item.pickup #(4)!

1. ID of the category.
2. Sets the NotifyIO type to be used.
3. An option of the advancementIO.
4. An option of the soundIO. Now, any notify event with money as its category will use the advancement io, with a gold_ingot for its icon and play the entity.item.pickup sound without you having to define all the options multiple times.

Warning

The only thing you must be careful with is the name of your custom categories. You could end up using a reserved name - these stem from BetonQuest's built-in notification categories. Changing these are a different feature. A full list of all reserved names can be found below.

Built-in Categories

Default Categories

By default, only 2 built-in categories exist: error/info.

The table below contains all built-in notification categories.

You may notice that the "Categories" column lists two categories: One that matches the name of the notification message and error/info.

These work exactly like the user-made categories in the notify event. The first existent category (from left to right) will be used. This allows you to change all built-in notifications with just two entries in your notifications section:

notifications:
  info:
    io: chat #(1)!
  error:
    io: actionbar #(2)!

1. Wouldn't actually change anything as chat is the default IO type.
2. Any message using the error category will now be displayed through the actionbar rather than chat.

You can override the settings from the info/error category for any specific notification by adding it to the notifications section. When you create a category with a name that matches a notification message name, BetonQuest then defaults to that option over error/info

Example

notifications:
  info:
    io: actionbar
  error:
    io: actionbar
  new_journal_entry:  
    io: subtitle #(1)!

1. Since new_journal_entry notification is now defined, the info category settings are overridden because the first existent category (from left to right) will be used.

Notifications	Categories
Command Blocked	command_blocked, error
No Permission	no_permission, error
Inventory Full Backpack	inventory_full_backpack, inventory_full, error
Inventory Full Drop	inventory_full_drop, inventory_full, error
Language Changed	language_changed, info
Quest Cancelled	quest_cancelled, info
New Journal Entry	new_journal_entry, info
Conversation start	conversation_start, info
Conversation end	conversation_end, info
Conversation blocked	busy, error
Money Given	money_given, info
Money Taken	money_taken, info
Items given	items_given, info
Items taken	items_taken, info
Points given	point_given, info
Points taken	point_taken, info
Points set	point_set, info

Notifications	Categories
Points multiplied	point_multiplied, info
Animals to Breed	animals_to_breed, info
Blocks to Break	blocks_to_break, info
Blocks to Place	blocks_to_place, info
Mobs to click	mobs_to_click, info
Mobs to Kill	mobs_to_kill, info
Fish to catch	fish_to_catch, info
Players to kill	players_to_kill, info
Potions to brew	potions_to_brew, info
Sheep to shear	sheep_to_shear, info
Times to jump	times_to_jump, info
Animals to bread	animals_to_tame, info
Payment to receive	payment_to_receive, info
Levels to gain	level_to_gain, info
Items to enchant	items_to_enchant, info
Items to craft	items_to_craft, info
Items to smelt	items_to_smelt, info
Items to pickup	items_to_pickup, info