Skip to content

Overlay

Jump to bottom
theblackswitch edited this page Jan 13, 2026 · 6 revisions

Available since version 2.0

Screen overlays are useful to pass data to the user in a stylish manner. As a result, this library contains a very extensive API for that.

Usage

In this library, overlays work much like attributes. You create one with an ID and then you use that ID to modify or remove it. This allows to specifically optimize each function.

Creating an overlay

To create an overlay you can run store your arguments in the storage theblackswitch:overlay and run the function as the target player:

data merge storage theblackswitch:overlay {<args>}
function #theblackswitch:<version>/overlay/add

Arguments:

  • texture: The overlay texture to apply
  • priority: The priority of the overlay. One of: persistent|conditional|notification|override (more info later)
  • id: the id of this overlay, used to refrence it later

Warning

The arguments will be cleared from the storage by the next tick!

Context:

  • Should run as the player which should receive the overlay

Modifying an overlay

To modify an overlay you can run store your arguments in the storage theblackswitch:overlay and run the function as the target player:

data merge storage theblackswitch:overlay {<args>}
function #theblackswitch:<version>/overlay/modify

Arguments:

  • texture: The replacing overlay texture
  • id: The id of the overlay to modify

Warning

The arguments will be cleared from the storage by the next tick!

Context:

  • Should run as the player whose overlay should be modified

Removing an overlay

To remove an overlay you can run store your arguments in the storage theblackswitch:overlay and run the function as the target player:

data merge storage theblackswitch:overlay {<args>}
function #theblackswitch:<version>/overlay/remove

Arguments:

  • id: The id of the overlay to remove

Warning

The arguments will be cleared from the storage by the next tick!

Context:

  • Should run as the player whose overlay should be removed

Priority

The priority field of an overlay is used to determine which overlays should be shown when multiple datapacks show multiple overlays. The API can show a maximum amount of 4 overlays at once. The list below will show the priorities in descending order so notification will override conditional for example.

  • override: This is the highest priority and will layer ontop of every other overlay
  • notification: This is the second highest priority and is utilized for overlays that are on the screen only for a short period of time. You can think of this for example as a toast popping in and out or a custom damage indicator firing.
  • conditional: This is the second lowest priority and is reserved for overlays that may be active for a long time but are only active on a condition. You can compare this for example to a custom 'blindness' overlay in your horror dimension or a freezing effect overlay (much like the vanilla minecraft one)
  • persistent: This is the lowest priority and is used for overlays that are always on the screen. This can for example be a custom HUD or background effects

Note

When multiple overlay's have the same priority, the newest overlay will be layered ontop of the older one(s).

Examples

A cutscene using an overlay to tell the user that it's a cutscene.

cutscene_start.mcfunction (runs as all players in the cutscene)

# show the overlay
data merge storage theblackswitch:overlay {"texture":"example:item/overlay/cutscene","id":"example:cutscene","priority":"conditional"}
function #theblackswitch:v2.0/overlay/add

cutscene_end.mcfunction (runs as all the players in the cutscene)

# remove the overlay
data merge storage theblackswitch:overlay {"id":"example:cutscene"}
function #theblackswitch:v2.0/overlay/remove

A cool message toast animation

message_toast/animation.mcfunction (runs as the player receiving the message)

# Init the animation
execute unless score @s toast.frame matches 0.. run scoreboard players set @s toast.frame 0

# Create a new overlay
execute if score @s toast.frame matches 0 run data merge storage theblackswitch:overlay {"id":"example:message","texture":"example:item/overlay/message_toast/frame_0","priority":"notification"}
execute if score @s toast.frame matches 0 run function #theblackswitch:v2.0/overlay/add

# All the frames of the animation [also if your datapack looks a lot like these repetetive commands, I recommend checking out beet (https://mcbeet.dev) ;)]
execute if score @s toast.frame matches 1 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_1","id":"example:message"}
execute if score @s toast.frame matches 2 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_2","id":"example:message"}
execute if score @s toast.frame matches 3 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_3","id":"example:message"}
execute if score @s toast.frame matches 4 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_4","id":"example:message"}
execute if score @s toast.frame matches 5 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_5","id":"example:message"}
execute if score @s toast.frame matches 6 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_6","id":"example:message"}
execute if score @s toast.frame matches 7 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_7","id":"example:message"}
execute if score @s toast.frame matches 8 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_8","id":"example:message"}
execute if score @s toast.frame matches 9 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_9","id":"example:message"}
execute if score @s toast.frame matches 10 run data merge storage theblackswitch:overlay {"texture":"example:item/overlay/message_toast/frame_10","id":"example:message"}
execute if score @s toast.frame matches 1..10 run function #theblackswitch:v2.0/overlay/modify

# remove the overlay when we're done
execute if score @s toast.frame matches 11 run data merge storage theblackswitch:overlay {"id":"example:message"}
execute if score @s toast.frame matches 11 run function #theblackswitch:v2.0/overlay/remove

scoreboard players add @s toast.frame 1

Enabling

This feature needs to be enabled using

function #theblackswitch:v2.0/overlay/enable

This feature doesn't use a ticking function, however, it does run when the player changes it's inventory and thus, can create some overhead.

Clone this wiki locally