From 0f4ca1d1a2712d29ffc2af07e68075be2691df68 Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Thu, 24 Sep 2026 14:48:32 +0000 Subject: [PATCH 1/4] docs: describe shared feature ownership and reversible upgrades --- projects/BirdMessenger/README.md | 4 + projects/BirdMessenger/overview.md | 4 +- projects/Cooking/README.md | 6 +- projects/Magic/README.md | 4 + projects/Magic/docs/SYSTEM.md | 4 +- projects/RPCharacters/README.md | 4 + projects/Research/README.md | 8 +- projects/Research/overview.md | 4 +- projects/TFMCCore/README.md | 3 +- projects/TFMCCore/ownership-migration.md | 109 +++++++++++++++++++++++ projects/TLibs/README.md | 6 +- 11 files changed, 145 insertions(+), 11 deletions(-) create mode 100644 projects/TFMCCore/ownership-migration.md diff --git a/projects/BirdMessenger/README.md b/projects/BirdMessenger/README.md index 5ab84f3..72be233 100644 --- a/projects/BirdMessenger/README.md +++ b/projects/BirdMessenger/README.md @@ -27,3 +27,7 @@ The manifest requires TLibs and marks RPCharacters, TFMCWeb and ItemsAdder optio ## Builds and releases See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access. + +## Shared feature ownership + +See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. diff --git a/projects/BirdMessenger/overview.md b/projects/BirdMessenger/overview.md index 62ae400..8899fa1 100644 --- a/projects/BirdMessenger/overview.md +++ b/projects/BirdMessenger/overview.md @@ -5,8 +5,8 @@ Right-click the mailbox to send letters. Ordinary left-clicks are protected; sneak-break to remove the mailbox deliberately. The default `letter: ia.iasurvival:letter` accepts blank, sealed and opened -letter variants, including for existing configurations. Custom legacy values -still match only that item. An optional `letters` list overrides `letter`: +letter variants, including for existing configurations. The default also accepts letter variants configured by the transferred sealing +feature. Custom legacy values still match only that item. An optional `letters` list overrides `letter`: ```yaml letters: diff --git a/projects/Cooking/README.md b/projects/Cooking/README.md index a3a0a0c..68bafa9 100644 --- a/projects/Cooking/README.md +++ b/projects/Cooking/README.md @@ -16,7 +16,7 @@ Use JDK 21, install the matching TLibs Maven artifact (`me.plugins:tlibs`, versi ## Runtime and configuration -The plugin registers food item paths with TLibs and integrates furniture stations, TFMCCore, crops and husbandry. The manifest requires TLibs, InteractibleFurniture and TFMCCore; RPCharacters, MMOCore, CustomCrops, SimpleFactions and CustomFishing enable additional integrations. `/cooking` requires `cooking.admin` (op by default). The guides below define crop and husbandry behavior and their configuration boundaries. +The plugin registers food item paths with TLibs and integrates furniture stations, TLibs inventory scanning, crops and husbandry. The manifest requires TLibs 2.1.0 or newer and InteractibleFurniture; RPCharacters, MMOCore, CustomCrops, SimpleFactions and CustomFishing enable additional integrations. `/cooking` requires `cooking.admin` (op by default). The guides below define crop and husbandry behavior and their configuration boundaries. ## Guides @@ -26,3 +26,7 @@ The plugin registers food item paths with TLibs and integrates furniture station ## Builds and releases See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access. + +## Shared feature ownership + +See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. diff --git a/projects/Magic/README.md b/projects/Magic/README.md index f62eb71..5b1df63 100644 --- a/projects/Magic/README.md +++ b/projects/Magic/README.md @@ -13,3 +13,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](.. ## Builds and releases See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access. + +## Shared feature ownership + +See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. diff --git a/projects/Magic/docs/SYSTEM.md b/projects/Magic/docs/SYSTEM.md index 9f50232..1ab6c54 100644 --- a/projects/Magic/docs/SYSTEM.md +++ b/projects/Magic/docs/SYSTEM.md @@ -88,7 +88,7 @@ Sit with GSit on the circle center (must be in a vehicle). Eight InteractibleFur No chat or action bar. A white starter orb appears in front of you; left-click hitscan (VehicleFramework-style) begins the orbit field. White orbs are Flow, red are Surge. Mix follows Equilibrium (`whiteChance = 0.5 * (1 + eq/max)`). Hitting red starts a 10s all-Surge lock; another red hit refreshes it. -Each hit costs 1 Focus (TFMCCore, character-keyed). Flow nudges Equilibrium up; Surge nudges it down. Resonance toward cap `sum(element power on sockets) / 8`. Charged artifacts supply usable aura, adjusted by their care state. Empty artifacts do not start a session; missing furniture means no session. +Each hit costs 1 Focus (RPCharacters, character-keyed). Flow nudges Equilibrium up; Surge nudges it down. Resonance toward cap `sum(element power on sockets) / 8`. Charged artifacts supply usable aura, adjusted by their care state. Empty artifacts do not start a session; missing furniture means no session. ## Persistence (MagicProfile) @@ -106,7 +106,7 @@ Admin `/magic open` without a character stays ephemeral (nothing saved). Drift s - **TLibs** (required) - item refs, formatHex - **ItemsAdder** (required) - `ia.` icons in gui.yml / elements -- **TFMCCore** (required) - character Focus pool +- **RPCharacters** (required, 2.1.0 or newer) - character Focus pool - **InteractibleFurniture** (required) - pedestals - **RPCharacters** (soft) - character head and per-character MagicProfile persistence diff --git a/projects/RPCharacters/README.md b/projects/RPCharacters/README.md index eb1bb94..dfbb0e2 100644 --- a/projects/RPCharacters/README.md +++ b/projects/RPCharacters/README.md @@ -20,3 +20,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](.. ## Builds and releases See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access. + +## Shared feature ownership + +See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. diff --git a/projects/Research/README.md b/projects/Research/README.md index 5c4818a..c5e88cb 100644 --- a/projects/Research/README.md +++ b/projects/Research/README.md @@ -10,12 +10,12 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](.. Research builds with Java **21** against `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs -`2.0.1` and TFMCCore `2.0.1` release artifacts with the shared dependency +`2.0.1` and RPCharacters `2.1.0` release artifacts with the shared dependency installer. The build also prepares checksum-verified MMOCore `1.13.1` and MythicLib `1.7` inputs from the private ServerAssets repository. At runtime, `plugin.yml` requires MMOItems, MythicLib, ItemsAdder, TLibs, and -TFMCCore. The code reaches MMOItems and ItemsAdder only through TLibs item +RPCharacters. The code reaches MMOItems and ItemsAdder only through TLibs item paths. MMOCore is declared as a soft dependency, but the discovery attribute lookup calls MMOCore classes directly, so install MMOCore wherever Research runs. @@ -28,3 +28,7 @@ runs. See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, private dependency access, and release verification. + +## Shared feature ownership + +See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. diff --git a/projects/Research/overview.md b/projects/Research/overview.md index bdd603b..242c1f0 100644 --- a/projects/Research/overview.md +++ b/projects/Research/overview.md @@ -113,9 +113,9 @@ open station menus before changing `labels` titles or `colors.inventory_title`. ## Integrations -- **TFMCCore Focus.** Mental points are the TFMCCore Focus pool for the player's +- **RPCharacters Focus.** Mental points are the RPCharacters Focus pool for the player's active RPCharacters character, shared with Magic meditation. The cap and - regeneration, including attribute bonuses, are set in TFMCCore `focus.yml`. A + regeneration, including attribute bonuses, are set in RPCharacters `focus.yml`. A player without an active character has no points and cannot experiment. - **MMOCore.** The discovery attribute is read as the attribute's total value; a missing attribute counts as zero. diff --git a/projects/TFMCCore/README.md b/projects/TFMCCore/README.md index 7349205..731d190 100644 --- a/projects/TFMCCore/README.md +++ b/projects/TFMCCore/README.md @@ -6,7 +6,8 @@ Technical documentation is maintained here. Run commands from the source checkou TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions. -- [README.md](overview.md) +- [Overview](overview.md) +- [Feature ownership, upgrade and rollback](ownership-migration.md) - [src/main/java/net/tfminecraft/tfmccore/stats/ARCHITECTURE.md](src/main/java/net/tfminecraft/tfmccore/stats/ARCHITECTURE.md) - [src/main/java/net/tfminecraft/tfmccore/stats/STATS.md](src/main/java/net/tfminecraft/tfmccore/stats/STATS.md) diff --git a/projects/TFMCCore/ownership-migration.md b/projects/TFMCCore/ownership-migration.md new file mode 100644 index 0000000..52e3bc8 --- /dev/null +++ b/projects/TFMCCore/ownership-migration.md @@ -0,0 +1,109 @@ +# Shared feature ownership and upgrades + +TFMCCore retains server rules, drops, MMOItems station interactions, statistics, +whistles and item name/lore stones. Shared scanning, character focus and letters +have these owners: + +| Feature | Runtime owner | Consumers / compatibility | +| --- | --- | --- | +| Inventory scanning | TLibs | Cooking and Magic subscribe through `net.tfminecraft.tlibs.itemscan`. Core's deprecated scanner API forwards to the same scanner. | +| Character focus | RPCharacters | Magic and Research use `RPCharacters.getFocusService()`. Core retains read/spend compatibility and `/tcore focus restore`. | +| Letter editing, sealing and opening | BirdMessenger | BirdMessenger also handles delivery. `/tcore reload letters` delegates to BirdMessenger. | + +No gameplay consumer needs TFMCCore for these three features after upgrading. +Core still needs TLibs and optionally integrates with RPCharacters and +BirdMessenger. Removing Core also removes its remaining gameplay features and +admin command aliases. + +## Build and release dependencies + +The new scanner consumers pin `me.plugins:tlibs:2.1.0`; the new focus consumers +pin `net.tfminecraft:rpcharacters:2.1.0`. Those are the first intended provider +release versions for these APIs. BirdMessenger's letter transfer targets 1.1.0. +A POM version is a requirement, not evidence that a release has been published. + +Build and release TLibs before its updated consumers. Build and release +RPCharacters before the updated Core, Magic and Research. Build BirdMessenger +before deploying Core's letter handoff. The release installer deliberately fails +if a pinned provider release is unavailable; do not substitute old jars under +new version coordinates. Dependent PRs remain drafts until provider releases +exist and their normal CI passes. + +For local coordinated validation, build the provider source and install its +candidate jar under the required new coordinate in a development Maven cache. +Record the source commit with the test results. A local candidate is not a +published release or suitable evidence of release provenance. + +## Runtime upgrade + +Use a stopped server for the ownership handoff; do not hot-reload these plugins. +Back up the plugin jars and the full TFMCCore, RPCharacters and BirdMessenger +configuration/data directories first. + +1. Install the scanner provider and updated Cooking/Magic consumers. Core's + compatibility API forwards older consumers to TLibs after Core is upgraded. + Before that, old consumers use the old scanner and new consumers use TLibs; + a consumer must subscribe through only one API. +2. Install the updated RPCharacters and Core together with the focus consumers. + RPCharacters copies missing legacy `TFMCCore/focus.yml` and + `TFMCCore/data/focus/*.json` into its own folder before creating defaults. + Existing destination files take precedence. Character IDs, points and + regeneration timestamps are preserved, and source files remain untouched. +3. Install the updated BirdMessenger with Core's letter handoff. + BirdMessenger copies a missing `letters-config.yml` from Core before creating + defaults. It continues recognizing the `tfmccore:sealed_letter` persistent + marker on existing items, including items stored in pending mail. + +Updated RPCharacters and BirdMessenger inspect the installed Core's bundled +`plugin.yml` ownership declarations before enabling the transferred features. +If a legacy Core is installed, they leave that feature with Core and log why. +They can provide these features without Core installed. This avoids two focus +writers or duplicate letter listeners when providers are upgraded first; it +does not make every new-consumer/old-provider combination supported. + +Core's `focus: RPCharacters` and `letters: BirdMessenger` ownership declarations +are part of the handoff protocol. Preserve them in custom builds. Configure focus +and letters in their new owners after migration; editing Core's old files will +no longer change those features. `/tcore reload focus` and +`/tcore reload letters` target the new owners. + +BirdMessenger preserves an explicit `letters` list or a custom legacy `letter` +setting. Its default acceptance also includes the transferred feature's configured +letter variants. Review explicit lists when migrating from the Core MMOItems +`m.books.*` defaults to a BirdMessenger installation using ItemsAdder letters. + +## Verification + +On Paper 1.21.10 with the matching plugin set, verify: + +- Cooking freshness and legacy fish conversion, Magic artifact updates, inventory + opens and pickups; no duplicate subscriptions or scanner tasks. +- Focus balance, spending, restoration, character switching, quitting/rejoining, + offline regeneration and restart persistence. Compare migrated JSON with the + source before gameplay changes it. +- Existing sealed letters open once with pages/title/author rules preserved; + newly edited, sealed and opened letters can be mailed according to the configured + acceptance list. Pending mail remains readable. +- A provider-only upgrade with legacy Core leaves ownership with Core and logs + the handoff requirement. Malformed migration input is reported rather than + silently replaced with fresh state. + +Unit tests and local compilation do not replace these server integration checks. + +## Rollback + +Stop the server before rolling back. Restore a mutually compatible set of plugin +jars; do not leave new consumers requiring APIs absent from old providers. + +Legacy files retained during migration are snapshots, not continuously updated +backups. If gameplay has continued under RPCharacters, preserve its current focus +files and copy the current `data/focus` records and `focus.yml` back to Core before +restoring the old focus owner. Back up both copies and reconcile conflicts rather +than overwriting newer balances blindly. Keep the new-owner directory for a +subsequent retry; reconcile it with Core again before another forward migration, +because existing destination records take precedence. + +Carry current BirdMessenger letter configuration back to Core if it changed. +Letters keep the original sealed marker, so no item rewrite is required. Keep +BirdMessenger mail data when restoring its previous jar. Do not delete the new +owner's files until rollback and a subsequent forward migration have been verified. diff --git a/projects/TLibs/README.md b/projects/TLibs/README.md index cc1270a..0c1f19e 100644 --- a/projects/TLibs/README.md +++ b/projects/TLibs/README.md @@ -2,7 +2,7 @@ [Source repository](https://github.com/TF-Minecraft/TLibs) ยท [All projects](../../README.md) -TLibs provides shared item and block APIs, MMOItems rebuild and socket handling, armour events, and SQLite helpers used by TFMC plugins. Run build commands from the `tlibs` source checkout. +TLibs provides shared item and block APIs, MMOItems rebuild and socket handling, armour events, inventory scanning, and SQLite helpers used by TFMC plugins. Run build commands from the `tlibs` source checkout. TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions. @@ -47,3 +47,7 @@ Pinned mode installs the versions declared in the consumer POM. Use `--mode latest` when intentionally upgrading those dependencies, then review and commit the POM changes. Release provenance records the exact source and build inputs. TLibs remains a separate server plugin. + +## Shared feature ownership + +See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. From 1cc8ec40687a55d7468757cc928debae53c28472 Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Thu, 24 Sep 2026 14:49:17 +0000 Subject: [PATCH 2/4] docs: align Magic dependency list with new providers --- projects/Magic/docs/SYSTEM.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/projects/Magic/docs/SYSTEM.md b/projects/Magic/docs/SYSTEM.md index 1ab6c54..628cdf4 100644 --- a/projects/Magic/docs/SYSTEM.md +++ b/projects/Magic/docs/SYSTEM.md @@ -104,11 +104,10 @@ Admin `/magic open` without a character stays ephemeral (nothing saved). Drift s ## Dependencies -- **TLibs** (required) - item refs, formatHex +- **TLibs** (required, 2.1.0 or newer) - item refs, formatHex, inventory scanning - **ItemsAdder** (required) - `ia.` icons in gui.yml / elements -- **RPCharacters** (required, 2.1.0 or newer) - character Focus pool +- **RPCharacters** (required, 2.1.0 or newer) - character Focus pool, character head and per-character MagicProfile persistence - **InteractibleFurniture** (required) - pedestals -- **RPCharacters** (soft) - character head and per-character MagicProfile persistence ## Commands From faec2c601ec31d90f257dce96da01a4cf764ca66 Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Thu, 24 Sep 2026 14:56:41 +0000 Subject: [PATCH 3/4] docs: describe current owners and manual server updates --- projects/BirdMessenger/README.md | 2 +- projects/Cooking/README.md | 2 +- projects/Magic/README.md | 2 +- projects/RPCharacters/README.md | 2 +- projects/Research/README.md | 2 +- projects/TFMCCore/README.md | 2 +- projects/TFMCCore/ownership-migration.md | 109 ----------------------- projects/TFMCCore/ownership.md | 90 +++++++++++++++++++ projects/TLibs/README.md | 2 +- 9 files changed, 97 insertions(+), 116 deletions(-) delete mode 100644 projects/TFMCCore/ownership-migration.md create mode 100644 projects/TFMCCore/ownership.md diff --git a/projects/BirdMessenger/README.md b/projects/BirdMessenger/README.md index 72be233..0f7ed77 100644 --- a/projects/BirdMessenger/README.md +++ b/projects/BirdMessenger/README.md @@ -30,4 +30,4 @@ See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, r ## Shared feature ownership -See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. +See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. diff --git a/projects/Cooking/README.md b/projects/Cooking/README.md index 68bafa9..acd86ad 100644 --- a/projects/Cooking/README.md +++ b/projects/Cooking/README.md @@ -29,4 +29,4 @@ See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, r ## Shared feature ownership -See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. +See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. diff --git a/projects/Magic/README.md b/projects/Magic/README.md index 5b1df63..3bb73e0 100644 --- a/projects/Magic/README.md +++ b/projects/Magic/README.md @@ -16,4 +16,4 @@ See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, r ## Shared feature ownership -See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. +See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. diff --git a/projects/RPCharacters/README.md b/projects/RPCharacters/README.md index dfbb0e2..55c043a 100644 --- a/projects/RPCharacters/README.md +++ b/projects/RPCharacters/README.md @@ -23,4 +23,4 @@ See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, r ## Shared feature ownership -See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. +See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. diff --git a/projects/Research/README.md b/projects/Research/README.md index c5e88cb..5bbd975 100644 --- a/projects/Research/README.md +++ b/projects/Research/README.md @@ -31,4 +31,4 @@ release tags, private dependency access, and release verification. ## Shared feature ownership -See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. +See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. diff --git a/projects/TFMCCore/README.md b/projects/TFMCCore/README.md index 731d190..a246ed1 100644 --- a/projects/TFMCCore/README.md +++ b/projects/TFMCCore/README.md @@ -7,7 +7,7 @@ Technical documentation is maintained here. Run commands from the source checkou TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions. - [Overview](overview.md) -- [Feature ownership, upgrade and rollback](ownership-migration.md) +- [Feature ownership and manual updates](ownership.md) - [src/main/java/net/tfminecraft/tfmccore/stats/ARCHITECTURE.md](src/main/java/net/tfminecraft/tfmccore/stats/ARCHITECTURE.md) - [src/main/java/net/tfminecraft/tfmccore/stats/STATS.md](src/main/java/net/tfminecraft/tfmccore/stats/STATS.md) diff --git a/projects/TFMCCore/ownership-migration.md b/projects/TFMCCore/ownership-migration.md deleted file mode 100644 index 52e3bc8..0000000 --- a/projects/TFMCCore/ownership-migration.md +++ /dev/null @@ -1,109 +0,0 @@ -# Shared feature ownership and upgrades - -TFMCCore retains server rules, drops, MMOItems station interactions, statistics, -whistles and item name/lore stones. Shared scanning, character focus and letters -have these owners: - -| Feature | Runtime owner | Consumers / compatibility | -| --- | --- | --- | -| Inventory scanning | TLibs | Cooking and Magic subscribe through `net.tfminecraft.tlibs.itemscan`. Core's deprecated scanner API forwards to the same scanner. | -| Character focus | RPCharacters | Magic and Research use `RPCharacters.getFocusService()`. Core retains read/spend compatibility and `/tcore focus restore`. | -| Letter editing, sealing and opening | BirdMessenger | BirdMessenger also handles delivery. `/tcore reload letters` delegates to BirdMessenger. | - -No gameplay consumer needs TFMCCore for these three features after upgrading. -Core still needs TLibs and optionally integrates with RPCharacters and -BirdMessenger. Removing Core also removes its remaining gameplay features and -admin command aliases. - -## Build and release dependencies - -The new scanner consumers pin `me.plugins:tlibs:2.1.0`; the new focus consumers -pin `net.tfminecraft:rpcharacters:2.1.0`. Those are the first intended provider -release versions for these APIs. BirdMessenger's letter transfer targets 1.1.0. -A POM version is a requirement, not evidence that a release has been published. - -Build and release TLibs before its updated consumers. Build and release -RPCharacters before the updated Core, Magic and Research. Build BirdMessenger -before deploying Core's letter handoff. The release installer deliberately fails -if a pinned provider release is unavailable; do not substitute old jars under -new version coordinates. Dependent PRs remain drafts until provider releases -exist and their normal CI passes. - -For local coordinated validation, build the provider source and install its -candidate jar under the required new coordinate in a development Maven cache. -Record the source commit with the test results. A local candidate is not a -published release or suitable evidence of release provenance. - -## Runtime upgrade - -Use a stopped server for the ownership handoff; do not hot-reload these plugins. -Back up the plugin jars and the full TFMCCore, RPCharacters and BirdMessenger -configuration/data directories first. - -1. Install the scanner provider and updated Cooking/Magic consumers. Core's - compatibility API forwards older consumers to TLibs after Core is upgraded. - Before that, old consumers use the old scanner and new consumers use TLibs; - a consumer must subscribe through only one API. -2. Install the updated RPCharacters and Core together with the focus consumers. - RPCharacters copies missing legacy `TFMCCore/focus.yml` and - `TFMCCore/data/focus/*.json` into its own folder before creating defaults. - Existing destination files take precedence. Character IDs, points and - regeneration timestamps are preserved, and source files remain untouched. -3. Install the updated BirdMessenger with Core's letter handoff. - BirdMessenger copies a missing `letters-config.yml` from Core before creating - defaults. It continues recognizing the `tfmccore:sealed_letter` persistent - marker on existing items, including items stored in pending mail. - -Updated RPCharacters and BirdMessenger inspect the installed Core's bundled -`plugin.yml` ownership declarations before enabling the transferred features. -If a legacy Core is installed, they leave that feature with Core and log why. -They can provide these features without Core installed. This avoids two focus -writers or duplicate letter listeners when providers are upgraded first; it -does not make every new-consumer/old-provider combination supported. - -Core's `focus: RPCharacters` and `letters: BirdMessenger` ownership declarations -are part of the handoff protocol. Preserve them in custom builds. Configure focus -and letters in their new owners after migration; editing Core's old files will -no longer change those features. `/tcore reload focus` and -`/tcore reload letters` target the new owners. - -BirdMessenger preserves an explicit `letters` list or a custom legacy `letter` -setting. Its default acceptance also includes the transferred feature's configured -letter variants. Review explicit lists when migrating from the Core MMOItems -`m.books.*` defaults to a BirdMessenger installation using ItemsAdder letters. - -## Verification - -On Paper 1.21.10 with the matching plugin set, verify: - -- Cooking freshness and legacy fish conversion, Magic artifact updates, inventory - opens and pickups; no duplicate subscriptions or scanner tasks. -- Focus balance, spending, restoration, character switching, quitting/rejoining, - offline regeneration and restart persistence. Compare migrated JSON with the - source before gameplay changes it. -- Existing sealed letters open once with pages/title/author rules preserved; - newly edited, sealed and opened letters can be mailed according to the configured - acceptance list. Pending mail remains readable. -- A provider-only upgrade with legacy Core leaves ownership with Core and logs - the handoff requirement. Malformed migration input is reported rather than - silently replaced with fresh state. - -Unit tests and local compilation do not replace these server integration checks. - -## Rollback - -Stop the server before rolling back. Restore a mutually compatible set of plugin -jars; do not leave new consumers requiring APIs absent from old providers. - -Legacy files retained during migration are snapshots, not continuously updated -backups. If gameplay has continued under RPCharacters, preserve its current focus -files and copy the current `data/focus` records and `focus.yml` back to Core before -restoring the old focus owner. Back up both copies and reconcile conflicts rather -than overwriting newer balances blindly. Keep the new-owner directory for a -subsequent retry; reconcile it with Core again before another forward migration, -because existing destination records take precedence. - -Carry current BirdMessenger letter configuration back to Core if it changed. -Letters keep the original sealed marker, so no item rewrite is required. Keep -BirdMessenger mail data when restoring its previous jar. Do not delete the new -owner's files until rollback and a subsequent forward migration have been verified. diff --git a/projects/TFMCCore/ownership.md b/projects/TFMCCore/ownership.md new file mode 100644 index 0000000..7545c89 --- /dev/null +++ b/projects/TFMCCore/ownership.md @@ -0,0 +1,90 @@ +# Shared feature ownership + +| Feature | Owner | API / administration | +| --- | --- | --- | +| Inventory scanning | TLibs | `net.tfminecraft.tlibs.itemscan.ItemScanService` and `ItemScanHandler` | +| Character focus | RPCharacters | `RPCharacters.getFocusService()`; `/focus restore ` and `/focus reload` | +| Letter editing, sealing and opening | BirdMessenger | `letters-config.yml`; `/birdmessenger reload` | + +Cooking and Magic subscribe directly to TLibs scanning. Magic and Research read +and spend focus through RPCharacters. These consumers do not depend on TFMCCore. +Core owns server rules, custom drops, MMOItems station interactions, statistics, +whistles and item name/lore stones. + +## Inventory scanning + +TLibs starts and stops the scanner with its own lifecycle. Consumers with a hard +TLibs dependency subscribe during enable and unsubscribe during disable. Only +TLibs calls `start` or `stop`. + +The scanner processes one online player every two ticks, scans inventory opens +immediately, and calls pickup handlers with a null inventory and slot -1. Handlers +run synchronously in registration order and own item mutation. The scanner uses +Paper's global Bukkit scheduler and does not support Folia. + +## Character focus + +RPCharacters owns `focus.yml` and `data/focus/.json`. Character +activation switches balances, quitting saves them, and one timer applies configured +regeneration. Point limits, attribute bonuses and offline regeneration are +configured in `focus.yml`. Corrupt or unreadable records are reported and leave +the affected character's focus unavailable; they are not replaced with fresh points. + +`RPCharacters.getFocusService()` exposes balance, maximum, spending, granting and +restoration. It returns null if focus has not started successfully. Administrators +need `rpchar.focus.admin` (operator by default) for `/focus restore ` and +`/focus reload`. RPCharacters' general reload also reloads focus configuration. + +## Letters + +BirdMessenger owns `letters-config.yml` and book edit/sign/open listeners, in +addition to delivery. The `tfmccore:sealed_letter` persistent item key remains the +stable identifier for sealed items; there is no alternative-key fallback. + +The default mail acceptance includes the configured blank/sealed/opened letter +variants. An explicit `letters` list or a custom `letter` setting remains +authoritative. Check that these settings accept the items used by the server. + +## Manual dev and main update + +The installations are controlled together. There are no automatic data imports, +version-detection paths, old API wrappers or old command aliases. Update the full +plugin set while each server is stopped. Complete and verify dev before main. + +Back up the plugin jars and all affected configuration/data folders. Before first +starting the updated plugins, manually copy these files under that server's +`plugins` directory: + +| Copy from | Copy to | +| --- | --- | +| `TFMCCore/focus.yml` | `RPCharacters/focus.yml` | +| `TFMCCore/data/focus/*.json` | `RPCharacters/data/focus/` (same filenames) | +| `TFMCCore/letters-config.yml` | `BirdMessenger/letters-config.yml` | + +Create destination directories as needed. Compare existing destination files +before copying and resolve differences explicitly; do not overwrite newer +balances or server settings. Keep the source copies in the backup until the +update is verified. Starting without the copies creates defaults/new focus state, +so perform the file transfer first. No scanner data needs moving. + +Install the updated TLibs, RPCharacters, BirdMessenger, Core, Cooking, Magic and +Research jars as one coordinated set. Update staff permissions and configured +commands to use `/focus` and `/birdmessenger reload`. Core's reload targets now +cover its own configuration, drops, stations, stats, whistle and lorestones. + +Consumer builds require TLibs 2.1.0 for scanning and RPCharacters 2.1.0 for focus; +BirdMessenger's letter feature targets 1.1.0. Publish provider releases before +building dependent consumers through the pinned-release CI. Local source-built +candidates can verify the changes together, but are not published releases. + +After startup, verify food freshness/fish conversion, artifact updates, focus +spending and character switching, offline regeneration, restart persistence, +letter editing/sealing/opening, and queued mail. Compare copied balances and item +content before exercising them. Repeat the same procedure on main after dev +passes. Unit tests do not replace these Paper integration checks. + +For rollback, stop the server and restore a compatible set of jars/configuration. +If players have used the updated system, manually reconcile the current +RPCharacters focus records back into Core before restoring its ownership; the +pre-update backup no longer contains the latest balances. Retain current mail +storage and reconcile any changed letter settings as well. diff --git a/projects/TLibs/README.md b/projects/TLibs/README.md index 0c1f19e..d472829 100644 --- a/projects/TLibs/README.md +++ b/projects/TLibs/README.md @@ -50,4 +50,4 @@ build inputs. TLibs remains a separate server plugin. ## Shared feature ownership -See [feature ownership and migration](../TFMCCore/ownership-migration.md) for scanner, focus and letter APIs, coordinated upgrades, and rollback. +See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. From ea97a89e171e6324380cb435c4435849eeaebd35 Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Thu, 24 Sep 2026 15:43:11 +0000 Subject: [PATCH 4/4] docs: add coordinated build and manual rollout checklist --- projects/TFMCCore/ownership.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/projects/TFMCCore/ownership.md b/projects/TFMCCore/ownership.md index 7545c89..879f9d7 100644 --- a/projects/TFMCCore/ownership.md +++ b/projects/TFMCCore/ownership.md @@ -45,6 +45,18 @@ The default mail acceptance includes the configured blank/sealed/opened letter variants. An explicit `letters` list or a custom `letter` setting remains authoritative. Check that these settings accept the items used by the server. +## Build order + +1. Build and publish TLibs 2.1.0 and RPCharacters 2.1.0 from their merged source. + Verify the release JARs, embedded versions, checksums and build metadata. +2. Build Cooking, Magic and Research against those published provider versions. + Require their pinned-dependency CI builds to pass. Build BirdMessenger and + TFMCCore from the merged source as well. +3. Stage all seven JARs together: TLibs, RPCharacters, Cooking, Magic, Research, + BirdMessenger and TFMCCore. Record the source commit and checksum of each JAR; + use the same verified set for dev and main. Publishing a release does not + update either server. + ## Manual dev and main update The installations are controlled together. There are no automatic data imports, @@ -71,6 +83,8 @@ Install the updated TLibs, RPCharacters, BirdMessenger, Core, Cooking, Magic and Research jars as one coordinated set. Update staff permissions and configured commands to use `/focus` and `/birdmessenger reload`. Core's reload targets now cover its own configuration, drops, stations, stats, whistle and lorestones. +Remove the replaced JARs from the plugins directory so each plugin has exactly +one installed JAR. Use a full stop/start rather than a plugin reload. Consumer builds require TLibs 2.1.0 for scanning and RPCharacters 2.1.0 for focus; BirdMessenger's letter feature targets 1.1.0. Publish provider releases before @@ -79,10 +93,14 @@ candidates can verify the changes together, but are not published releases. After startup, verify food freshness/fish conversion, artifact updates, focus spending and character switching, offline regeneration, restart persistence, -letter editing/sealing/opening, and queued mail. Compare copied balances and item +letter editing/sealing/opening in both hands, and queued mail. Compare copied balances and item content before exercising them. Repeat the same procedure on main after dev passes. Unit tests do not replace these Paper integration checks. +Copy main's own current files during main's maintenance window; do not copy dev's +focus balances over main. Sealed items keep their existing identifier and need +no item conversion. No scanner files need transferring. + For rollback, stop the server and restore a compatible set of jars/configuration. If players have used the updated system, manually reconcile the current RPCharacters focus records back into Core before restoring its ownership; the