Skip to content

adventure_api.md

Latest commit

 

History

History
378 lines (278 loc) · 9.27 KB

adventure_api.md

File metadata and controls

378 lines (278 loc) · 9.27 KB
Raw

Adventure API Documentation

The Adventure API provides Lua scripts with access to the Kyori Adventure library for advanced text formatting, boss bars, titles, action bars, sounds, and more in Minecraft.

Global Access

The API is accessed via the global AdventureApi table in Lua scripts.

Methods

sendColored

Sends a colored text message to an audience.

Syntax:

AdventureApi:sendColored(audience, color, message, [decoration])

Parameters:

  • audience (userdata): The target audience (e.g., player, console)
  • color (string): Color name (case-insensitive). Valid colors: red, green, blue, yellow, white, black, dark_red, dark_green, dark_blue, dark_aqua, dark_purple, gold, gray, dark_gray, aqua, light_purple
  • message (string): The text message to send
  • decoration (string, optional): Text decoration. Valid values: bold, italic, underline/underlined, strikethrough/strike, obfuscated/magic

Example:

AdventureApi:sendColored(sender, "red", "This is red text", "bold")
AdventureApi:sendColored(sender, "green", "This is green text")

sendLink

Sends a clickable link message to an audience.

Syntax:

AdventureApi:sendLink(audience, message, url, [color], [decoration])

Parameters:

  • audience (userdata): The target audience
  • message (string): The text to display
  • url (string): The URL to open when clicked
  • color (string, optional): Color name (defaults to white)
  • decoration (string, optional): Text decoration

Example:

AdventureApi:sendLink(sender, "Click here for Google", "https://google.com", "blue", "underline")

sendHover

Sends a message with hover text to an audience.

Syntax:

AdventureApi:sendHover(audience, message, hoverText, [color], [decoration])

Parameters:

  • audience (userdata): The target audience
  • message (string): The text to display
  • hoverText (string): The text to show when hovering
  • color (string, optional): Color name (defaults to white)
  • decoration (string, optional): Text decoration

Example:

AdventureApi:sendHover(sender, "Hover over me!", "This is hover text", "yellow", "bold")

sendMiniMessage

Sends a message formatted with MiniMessage syntax.

Syntax:

AdventureApi:sendMiniMessage(audience, miniMessageString)

Parameters:

  • audience (userdata): The target audience
  • miniMessageString (string): MiniMessage formatted string (e.g., <red>text</red>, <gradient:gold:white>text</gradient>)

Example:

AdventureApi:sendMiniMessage(sender, "<red>Red mini message</red> and <bold>bold text</bold>")
AdventureApi:sendMiniMessage(sender, "<gradient:gold:white>Gradient text!</gradient>")

sendTranslatable

Sends a translatable message using Minecraft's translation keys.

Syntax:

AdventureApi:sendTranslatable(audience, translationKey, [args...])

Parameters:

  • audience (userdata): The target audience
  • translationKey (string): Minecraft translation key (e.g., block.minecraft.stone)
  • args... (string, optional): Arguments to substitute into the translation

Example:

AdventureApi:sendTranslatable(sender, "block.minecraft.stone")
AdventureApi:sendTranslatable(sender, "death.fell.accident.generic", "Player")

sendInsertion

Sends a message with insertion text (shift-click to insert into chat).

Syntax:

AdventureApi:sendInsertion(audience, message, insertionText, [color], [decoration])

Parameters:

  • audience (userdata): The target audience
  • message (string): The text to display
  • insertionText (string): The text to insert when shift-clicked
  • color (string, optional): Color name (defaults to white)
  • decoration (string, optional): Text decoration

Example:

AdventureApi:sendInsertion(sender, "Shift-click me!", "inserted_text", "aqua", "italic")

sendTitle

Sends a title and subtitle to an audience.

Syntax:

AdventureApi:sendTitle(audience, title, [subtitle], [fadeIn], [stay], [fadeOut])

Parameters:

  • audience (userdata): The target audience
  • title (string): The main title text
  • subtitle (string, optional): The subtitle text
  • fadeIn (number, optional): Fade-in duration in milliseconds (must be used with stay)
  • stay (number, optional): Stay duration in milliseconds (must be used with fadeIn)
  • fadeOut (number, optional): Fade-out duration in milliseconds (defaults to 1000)

Example:

AdventureApi:sendTitle(sender, "Main Title", "Subtitle text")
AdventureApi:sendTitle(sender, "Timed Title", "With timing", 500, 1500, 500)

sendActionBar

Sends a message to the action bar.

Syntax:

AdventureApi:sendActionBar(audience, message)

Parameters:

  • audience (userdata): The target audience
  • message (string): The message to display

Example:

AdventureApi:sendActionBar(sender, "This is an action bar message")

sendBossBar

Creates and displays a boss bar for an audience.

Syntax:

local bossBar = AdventureApi:sendBossBar(audience, title, progress, [color])

Parameters:

  • audience (userdata): The target audience
  • title (string): The boss bar title
  • progress (number): Progress value between 0.0 and 1.0 (clamped if out of range)
  • color (string, optional): Color name (defaults to pink). Maps string color names to Bukkit BarColor enum values: red→RED, green→GREEN, blue→BLUE, yellow→YELLOW, white→WHITE, all other colors→PINK

Returns:

  • bossBar (userdata): The BossBar object (use with hideBossBar)

Example:

local bossBar = AdventureApi:sendBossBar(sender, "Test Boss Bar", 0.5, "red")

hideBossBar

Hides a previously shown boss bar.

Syntax:

AdventureApi:hideBossBar(audience, bossBar)

Parameters:

  • audience (userdata): The target audience
  • bossBar (userdata): The BossBar object returned by sendBossBar

Example:

local bossBar = AdventureApi:sendBossBar(sender, "Test Boss Bar", 0.5, "red")
-- ... later ...
AdventureApi:hideBossBar(sender, bossBar)

playSound

Plays a sound for an audience.

Syntax:

AdventureApi:playSound(audience, soundKey, [volume], [pitch])

Parameters:

  • audience (userdata): The target audience
  • soundKey (string): Minecraft sound key (e.g., entity.player.levelup, block.note_block.pling)
  • volume (number, optional): Volume (defaults to 1.0)
  • pitch (number, optional): Pitch (defaults to 1.0)

Example:

AdventureApi:playSound(sender, "entity.player.levelup", 1.0, 1.0)
AdventureApi:playSound(sender, "block.note_block.pling", 0.5, 2.0)

parseLegacy

Parses and sends a legacy format string (using & color codes).

Syntax:

AdventureApi:parseLegacy(audience, legacyString)

Parameters:

  • audience (userdata): The target audience
  • legacyString (string): Legacy format string with & color codes (e.g., &cRed &lBold)

Color Codes:

  • &0 - Black
  • &1 - Dark Blue
  • &2 - Dark Green
  • &3 - Dark Aqua
  • &4 - Dark Red
  • &5 - Dark Purple
  • &6 - Gold
  • &7 - Gray
  • &8 - Dark Gray
  • &9 - Blue
  • &a - Green
  • &b - Aqua
  • &c - Red
  • &d - Light Purple
  • &e - Yellow
  • &f - White
  • &l - Bold
  • &o - Italic
  • &n - Underline
  • &m - Strikethrough
  • &k - Obfuscated
  • &r - Reset

Example:

AdventureApi:parseLegacy(sender, "&cRed &lBold &eYellow &rReset")

joinComponents

Joins multiple text strings with a separator and sends them.

Syntax:

AdventureApi:joinComponents(audience, separator, message1, message2, ...)

Parameters:

  • audience (userdata): The target audience
  • separator (string): The separator text between messages
  • message1, message2, ... (string): The messages to join

Example:

AdventureApi:joinComponents(sender, " | ", "First", "Second", "Third", "Fourth")

buildComponent

Builds a text component object for later use.

Syntax:

local component = AdventureApi:buildComponent(text, [color], [decoration])

Parameters:

  • text (string): The text content
  • color (string, optional): Color name (defaults to white)
  • decoration (string, optional): Text decoration

Returns:

  • component (userdata): A Component object (for advanced use with custom Adventure API extensions)

Example:

local component = AdventureApi:buildComponent("Custom component", "light_purple", "bold")

parseMiniMessage

Parses a MiniMessage string and returns a Component object (without sending it).

Syntax:

local component = AdventureApi:parseMiniMessage(miniMessageString)

Parameters:

  • miniMessageString (string): MiniMessage formatted string (e.g., <red>text</red>, <gradient:gold:white>text</gradient>)

Returns:

  • component (userdata): A Component object

Example:

local component = AdventureApi:parseMiniMessage("<red>Red text</red>")
-- Use the component later with other APIs

Notes

  • All color names are case-insensitive
  • Decoration names support aliases: underline/underlined, strikethrough/strike, obfuscated/magic
  • Boss bars must be manually hidden using hideBossBar to prevent resource leaks
  • Invalid colors/decorations will log a warning and fall back to defaults