mailboxes - STEMMechanics/STEMCraft GitHub Wiki

Mailboxes

The mailbox feature provides delayed player-to-player and server-to-player deliveries. Every delivery contains a written book identifying the sender, the optional message, and the supplied items.

Player workflow

Players place a mailbox using the configured custom recipe. Closing a mailbox with items in it opens a compose dialog with recipient, message, Send, and Cancel controls. Java uses Paper dialogs; Bedrock uses a Geyser form.

When delivery completes, the recipient receives the configured notification. Notifications for offline recipients are stored and delivered when they next join. A player-specific hologram appears above every mailbox while that player has delivered mail waiting.

Administration command

/mailbox send <player> [message]

This queues a letter-only delivery. Player command senders are identified by UUID; console mail uses STEMCraft as its sender label. The other /mailbox subcommands inspect and administer the delivery queue.

Admin mail drafts

Use /mail to build a delivery containing a message and items:

/mail compose <player>
/mail message
/mail message save
/mail item add <item-id> <qty>
/mail item list
/mail item remove <item-id> <qty>
/mail preview
/mail send
/mail cancel

/mail message gives an in-game sender a writable book prefilled with the current draft message. Edit its pages, including blank lines, choose Done, then run /mail message save while the book is in your inventory. Saving copies the pages into the draft and removes the temporary book. /mail message <text> still replaces the message directly and works from console. Use /mail message -a <text> to append a new paragraph; literal \n sequences become line breaks. /mail preview opens the draft's actual written-book letter, including the sender, message and item list, without sending it; preview is available to in-game senders. Long messages are paginated in the generated letter. Recipients can be online or offline players known to the server. Item IDs accept vanilla names such as minecraft:diamond, minecraft:firework_rocket, and minecraft:golden_apple, or registered custom item IDs. The draft checks mailbox capacity before adding items; every sent delivery includes its letter.

For example, to reward a challenge winner:

/mail compose WinnerName
/mail message
# Edit the book, choose Done, then save its pages to the draft
/mail message save
/mail message -a Thanks for building such a great space station!
/mail item add minecraft:diamond 1
/mail item add minecraft:firework_rocket 8
/mail item add minecraft:golden_apple 1
/mail send

Each command sender can have one draft at a time. Use /mail item list to review it, /mail send to queue it, or /mail cancel to discard it. Player senders are identified by UUID; console drafts use STEMCraft as their sender label.

/mailbox send requires stemcraft.mailbox.send or an administrative mailbox permission. The /mail item draft command requires stemcraft.mailbox.admin or the legacy administrative permission stemcraft.mailbox.

Configuration

Runtime settings are under mailboxes in the main config.yml:

mailboxes:
  enabled: true
  hologram:
    text: ":mail_large:"
  delivery:
    base-delay: 72000
    process-mail-queue: 20
    mailbox-full-cooldown: 72000

hologram.text accepts plain text, MiniMessage formatting, and registered glyph tokens. Glyph assets are defined separately in the stemcraft-mail data pack.

Dialog labels and messages are configurable under mailboxes.dialog and mailboxes.messages.

Sending mail through the API

Recipients are identified only by UUID. Their current known name is resolved internally.

Mail may be sent as a player UUID or as a named server/plugin system.

Check result.queued() before treating the send as successful. result.message() describes failures, including unknown UUIDs or payloads that cannot fit in a mailbox.

MailboxService#hasMail(UUID) reports whether the player has delivered mail waiting.

Public API for sending and querying mailbox deliveries.

send()

Queues mail for delivery. A written letter is generated automatically and included with any supplied items; an empty item list sends a letter only.

Parameters

  • request — sender, recipient, message, items, and optional delivery delay

Returns

  • whether the delivery was queued and an explanatory failure message

Example: Sending system mail

MailSendResult result = api.mailboxes().send(new MailSendRequest(
    "STEMCraft",
    recipientUuid,
    "Your weekly reward",
    rewardItems
));

Example: Sending player mail

MailSendResult result = api.mailboxes().send(new MailSendRequest(
    senderUuid,
    recipientUuid,
    "Thanks for helping!",
    List.of(new ItemStack(Material.DIAMOND, 3))
));

hasMail()

Returns whether the player's delivered inbox currently contains mail.

Parameters

  • playerUuid — player whose delivered inbox should be checked

Returns

  • true when delivered mail is waiting

Dynamic holograms

Mailbox indicators use the dynamic hologram API with the stable key mailbox:<placed-object-id>. The hologram service owns Java and Bedrock entities, per-player visibility, range checks, world changes, chunk loading, entity anchors, and resource-pack token refreshes. Breaking a mailbox deletes its dynamic hologram by the same key; mailbox records do not store hologram entity IDs.

⚠️ **GitHub.com Fallback** ⚠️