Actionbar Overwrite & Priority System

FuseBox features a built-in actionbar overwrite engine that allows datapacks to display temporary custom JSON text messages for a set duration without interfering with active timers.

1. Actionbar Overwrite Function: /function fb:display/ab/overwrite

Displays a custom JSON text component on the actionbar for a specified duration in Minecraft ticks (20 ticks = 1 second). While active, it temporarily overrides any running stopwatch or countdown display. Once the duration expires, FuseBox automatically reverts to normal timer rendering.

/function fb:display/ab/overwrite {player:"@a",text:'{"text":"Speed Boost Active!","color":"gold","bold":true}',duration:100}

Parameter Reference

Parameter	Type	Description
player	String	Target selector (e.g. "@a", "@s", or player name).
text	String / JSON Component	Raw Minecraft JSON text component string (e.g. '{"text":"Message","color":"gold"}').
duration	Integer	Display duration in ticks (e.g. 100 ticks = 5 seconds). Sets score fb.ab_over on player.

2. Under the Hood Mechanics

• Stores the custom JSON text payload in storage fb:overwrite <player>.text.
• Sets the fb.ab_over scoreboard objective on target players to the specified duration value.
• During each tick, FuseBox's display loop checks if fb.ab_over > 0. If positive, it renders the custom JSON text component and decrements the score by 1.
• When fb.ab_over reaches 0, the overwrite automatically expires and normal timer displays resume seamlessly.

Event System API

Register reactive player events with item_id and custom_data NBT component filters.

Standard Events

• onJoin: Fires when a player logs in or joins the world.
• onDeath: Fires immediately when a player dies.
• onLeave: Fires immediately when a player disconnects or leaves.
• onKillPlayer: Fires as the killer when they kill another player.
• onKilledByPlayer: Fires as the victim when killed by another player.
• onDamage: Fires as the player when they take damage from any source.
• onEntityKill: Fires as the player when they kill a mob/monster.
• whileOnline: Fires every tick for all players currently online.
• whileOffline: Fires every tick for all registered players currently offline.

Item-Specific Events

• onRightClick: Fires when a player right-clicks holding a Carrot on a Stick or Warped Fungus on a Stick.
• onHoldItem: Fires every tick while a player is holding a specific item.

API Registration Commands

1. Function Callbacks (Standard Events):

/function fb:event/register {event:"onJoin", fn:"my_pack:welcome"}

2. Direct Command Callbacks (Standard Events):

/function fb:event/register_cmd {event:"onJoin", cmd:"say Welcome back, @s!"}

3. Function Callbacks (Item Events with custom_data):

/function fb:event/register_item {event:"onRightClick", fn:"my_pack:cast_spell", item_id:"minecraft:carrot_on_a_stick", custom_data:{id:"ascend"}}

4. Direct Command Callbacks (Item Events with custom_data):

/function fb:event/register_item_cmd {event:"onRightClick", cmd:"effect give @s speed 5 1", item_id:"minecraft:carrot_on_a_stick", custom_data:{id:"ascend"}}

Example Custom Macro Callback Function

Create a macro function in your custom datapack that receives macro arguments from FuseBox:

# my_pack/data/my_pack/function/welcome_macro.mcfunction
# Macro Arguments: player, event

$tellraw @a [{"text":"[Server] Welcome ","color":"gold"},{"text":"$(player)","color":"yellow","bold":true},{"text":"! Triggered ","color":"gold"},{"text":"$(event)","color":"aqua"}]

Stopwatch API Reference

Create and display live actionbar stopwatches for players with full control over formats, colors, and global display priorities.

Standard 3-Step Workflow

Step 1. Create / Initialize Stopwatch Instance:

/function fb:sw/create {name:"demo"}

Step 2. Bind Actionbar Display (Custom Formatting & Priority):

/function fb:sw/display_ab_custom {player:"@a", sw:"demo", format:"digital_short", color:"gold", color_sec:"yellow", color_num:"white", prefix:"Timer: ", suffix:"", bold:"false", global_type:"soft"}

Step 3. State Control (Pause, Resume, Reset):

/function fb:sw/pause {name:"demo"}
/function fb:sw/resume {name:"demo"}
/function fb:sw/reset-db

Stopwatch Functions & Macro Signatures

Function Call	Exact NBT Macro Arguments Signature	Description
fb:sw/create	/function fb:sw/create {name:"demo"}	Initializes a new stopwatch instance named demo (starts timer scores at 0).
fb:sw/display_ab_custom	/function fb:sw/display_ab_custom {player:"@a", sw:"demo", format:"digital_short", color:"gold", color_sec:"yellow", color_num:"white", prefix:"Timer: ", suffix:"", bold:"false", global_type:"soft"}	Configures custom actionbar display for demo timer with colors, prefix, format, and global priority.
fb:sw/display_ab	/function fb:sw/display_ab {player:"@a", sw:"demo"}	Binds stopwatch demo to actionbar display using default formatting.
fb:sw/pause	/function fb:sw/pause {name:"demo"}	Pauses tick counting for stopwatch demo.
fb:sw/resume	/function fb:sw/resume {name:"demo"}	Resumes tick counting for stopwatch demo.
fb:sw/reset-db	/function fb:sw/reset-db	Wipes all stopwatch instances and scoreboards.

Parameter Reference

Parameter	Type	Description
name	String	Stopwatch identifier string (e.g. demo). Used in create, pause, resume.
player	String	Target selector or player name (e.g. @a, @s, or player name).
sw	String	Stopwatch identifier string passed to display_ab_custom (e.g. demo).
format	String	digital (HH:MM:SS), digital_short (MM:SS.ms), letters (Xd Xh Xm Xs), dynamic.
color, color_sec, color_num	String	Color tag options for primary text, separators, and digit numbers.
prefix, suffix, bold, global_type	String	Display prefix, suffix, bold formatting, and global priority settings ("soft" / "hard").

Countdown API Reference

Create countdowns with automatic expiry commands and custom actionbar displays.

Standard 4-Step Workflow

Step 1. Create Countdown Instance (Duration & Expiry Command):

/function fb:cd/create {name:"timer1", h:0, m:1, s:30, on_complete:'data get storage fb:tmp dummy'}

Step 2. Bind Actionbar Display (Custom Formatting & Priority):

/function fb:cd/display_ab_custom {player:"@a", cd:"timer1", format:"digital_short", color:"red", color_sec:"gray", color_num:"white", prefix:"Time Left: ", suffix:"", bold:"false", global_type:"soft"}

Step 3. Start Countdown:

/function fb:cd/start {name:"timer1"}

Step 4. State Control (Pause, Resume, Delete):

/function fb:cd/pause {name:"timer1"}
/function fb:cd/resume {name:"timer1"}
/function fb:cd/delete {name:"timer1"}

Countdown Functions & Macro Signatures

Function Call	Exact NBT Macro Arguments Signature	Description
fb:cd/create	/function fb:cd/create {name:"timer1", h:0, m:1, s:30, on_complete:'data get storage fb:tmp dummy'}	Initializes countdown instance with hours, minutes, seconds, and expiry command.
fb:cd/display_ab_custom	/function fb:cd/display_ab_custom {player:"@a", cd:"timer1", format:"digital_short", color:"red", color_sec:"gray", color_num:"white", prefix:"Time Left: ", suffix:"", bold:"false", global_type:"soft"}	Configures custom actionbar display for timer1 with colors, prefix, format, and global priority.
fb:cd/display_ab	/function fb:cd/display_ab {player:"@a", cd:"timer1"}	Binds countdown timer1 to actionbar display using default formatting.
fb:cd/start	/function fb:cd/start {name:"timer1"}	Starts running countdown timer1.
fb:cd/pause	/function fb:cd/pause {name:"timer1"}	Pauses running countdown timer1.
fb:cd/resume	/function fb:cd/resume {name:"timer1"}	Resumes countdown timer1.
fb:cd/delete	/function fb:cd/delete {name:"timer1"}	Deletes countdown timer1 instance and resets its scoreboards.
fb:cd/reset-db	/function fb:cd/reset-db	Wipes all countdown instances and scoreboards.

Parameter Reference

Parameter	Type	Description
name	String	Countdown identifier string (e.g. timer1). Used in create, start, pause, resume, delete.
h, m, s	Integer	Initial duration hours, minutes, and seconds.
on_complete	String	Expiry command executed as player when countdown reaches 0 (e.g. 'say Time is up!').
player	String	Target selector or player name (e.g. @a, @s, or player name).
cd	String	Countdown identifier string passed to display_ab_custom (e.g. timer1).
format, color, prefix	String	Formatting settings for the countdown actionbar display.

Datapack Dependency Check

If you are developing a custom datapack that requires FuseBox, add this check to your pack's load.mcfunction to verify if FuseBox is installed and up-to-date:

# 1. Initialize temporary check objective
scoreboard objectives add fb.version dummy
scoreboard players set #fb_installed fb.version 0

# 2. Call FuseBox version check function
function fb:api/check_version

# 3. Check results and display errors/warnings
execute if score #fb_installed fb.version matches 0 run tellraw @a [{"text": "[my_pack] ", "color": "gold", "bold": true}, {"text": "Error: FuseBox is NOT installed! This pack requires FuseBox v0.1 Alpha or newer.", "color": "red"}]
execute if score #fb_installed fb.version matches 1.. if score #fb_installed fb.version matches ..0 run tellraw @a [{"text": "[my_pack] ", "color": "gold", "bold": true}, {"text": "Warning: FuseBox is out of date! Please update FuseBox to at least v0.1 Alpha.", "color": "red"}]

Debugging & Diagnostics

FuseBox features built-in tools to inspect NBT storages and toggle chat diagnostics.

1. In-Game Debug Menu

/function fb:debug/menu

2. Toggle Chat Diagnostics

# Turn debug ON
/data modify storage fb:config debug set value 1b

# Turn debug OFF
/data modify storage fb:config debug set value 0b

3. Inspect Registrations

/function fb:sw/debug_info
/function fb:cd/debug_info
/function fb:event/debug_info