diff --git a/projects/BirdMessenger/README.md b/projects/BirdMessenger/README.md index 5ab84f3..0f7ed77 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 manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. 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..acd86ad 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 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 f62eb71..3bb73e0 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 manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. diff --git a/projects/Magic/docs/SYSTEM.md b/projects/Magic/docs/SYSTEM.md index 9f50232..628cdf4 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) @@ -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 -- **TFMCCore** (required) - 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 diff --git a/projects/RPCharacters/README.md b/projects/RPCharacters/README.md index eb1bb94..55c043a 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 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 5c4818a..5bbd975 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 manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps. 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..a246ed1 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 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.md b/projects/TFMCCore/ownership.md new file mode 100644 index 0000000..879f9d7 --- /dev/null +++ b/projects/TFMCCore/ownership.md @@ -0,0 +1,108 @@ +# 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. + +## 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, +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. +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 +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 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 +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 cc1270a..d472829 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 manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps.