diff --git a/projects/BirdMessenger/README.md b/projects/BirdMessenger/README.md index 29a7d67..9cee14d 100644 --- a/projects/BirdMessenger/README.md +++ b/projects/BirdMessenger/README.md @@ -10,7 +10,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](.. Run Maven with **JDK 21** from the source checkout. The POM sets `maven.compiler.release=21` and resolves `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT` with `provided` scope from the PaperMC Maven repository. The plugin descriptor declares `api-version: 1.21.10`. -Install these matching Java 21 TFMC artifacts into local Maven before building: `me.plugins:tlibs:2.0.0`, `net.tfminecraft:rpcharacters:2.0.1`. Use the [shared installer](../TLibs/README.md) for published dependencies, or `mvn clean install` from matching source versions. CI uses the shared dependency setup actions. +Install these matching Java 21 TFMC artifacts into local Maven before building: `me.plugins:tlibs:2.3.0`, `net.tfminecraft:rpcharacters:2.16.0`. Use the [shared installer](../TLibs/README.md) for published dependencies, or `mvn clean install` from matching source versions. CI uses the shared dependency setup actions. Populate `libs/` with the exact files and hashes listed in `.github/dependencies.sha256`. `.github/scripts/prepare-release.sh` downloads those pinned private assets when supplied with the approved dependency token. @@ -34,7 +34,7 @@ Use `mvn clean install` when another plugin needs the result as a Maven dependen ## Runtime and configuration -The manifest requires TLibs and marks RPCharacters, TFMCWeb and ItemsAdder optional. The character picker needs RPCharacters; furniture mailboxes need ItemsAdder; offline Discord notifications need TFMCWeb and `discord.enabled`. `/birdmessenger reload` requires `birdmessenger.reload` (op by default). See the mailbox guide below for interaction checks. +The manifest requires TLibs and marks RPCharacters, TFMCWeb and ItemsAdder optional. Sending requires a ready character session from TLibs, and the character picker needs RPCharacters; furniture mailboxes need ItemsAdder; offline Discord notifications need TFMCWeb and `discord.enabled`. `/birdmessenger reload` requires `birdmessenger.reload` (op by default). See the mailbox guide below for interaction checks. ## Guides diff --git a/projects/BirdMessenger/overview.md b/projects/BirdMessenger/overview.md index f1f6ec5..c9e7538 100644 --- a/projects/BirdMessenger/overview.md +++ b/projects/BirdMessenger/overview.md @@ -23,6 +23,37 @@ character from the recipient list, or `/rpcharacter mail on` to restore it. If a recipient opts out before a sender confirms, the letter is returned; already-sent mail still arrives. +## Character sessions + +Mailbox sending requires a ready character. The letter slot, recipient picker, +queued picker opening and skin refresh belong to the same player connection and +character activation. Switching away and back does not revive an old menu. +Ending that session closes its menus and returns unsent letters to the outgoing +inventory before RPCharacters saves it. Plugin shutdown also returns letters from +current sessions. When that inventory is no longer safe to use, the letter is +queued for its captured owner and character instead. Storage errors are logged; +failed unsent refunds remain in memory for retry on character start and plugin +shutdown. Repair a reported storage problem before stopping the plugin. + +Letter editing, signing and opening preserve the original item checks and also +verify the captured session before changing an item on the next tick. While a +character provider is registered but no character is ready, edits and signatures +are refused; sealed books remain readable without rewriting the item. Standalone +letter editing remains available without a provider, provided one has not arrived +before the delayed write. + +In-flight mail belongs to the recipient character and survives session changes. +Delivery requires a ready session for the stored owner and character. Pending +mail is removed one letter at a time, checking the same session between letters; +a switch during delivery leaves the rest queued. Existing UUID text is preserved, +including uppercase spelling. Malformed character IDs and mail for another owner +are retained and are not delivered to the current character. + +The shared TLibs API supplies session identity. RPCharacters still supplies the +mail-specific opted-in recipient list, head textures and flight destinations. +BirdMessenger requires TLibs 2.3.0 or newer; missing provider registration blocks +sending and delivery until it becomes available. + ## Mail recovery Mail is stored in `plugins/BirdMessenger/in_flight_mail.yml` and @@ -45,3 +76,11 @@ Before deployment, verify on a test server with ItemsAdder: - Sneak-break: the mailbox can be removed, subject to existing region protection. - Right-click and send sealed and opened letters: pages and delivery stay intact. - Unrelated items and ordinary books are rejected; other furniture breaks normally. +- Switch characters from both the letter slot and recipient picker: the outgoing + character keeps the unsent letter and the next character receives no stale menu. +- Switch away and back while a picker refresh or letter edit is queued: old work + cannot change the current inventory. +- Receive several pending letters, switching during delivery: remaining letters + wait for a ready session of their stored owner and character. +- Restart with pending and in-flight mail: delivery resumes without changing + recipient opt-out behavior or stored character IDs.