Infestations: death on login reaches only the character who logged off

projects/Infestations/README.md

@@ -10,15 +10,15 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 
 Infestations builds with Java **21** against
 `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs
-`2.0.1`, SimpleFactions `3.0.2`, and InteractibleFurniture `0.2.1` release
-artifacts with the shared dependency installer. The build also prepares a
-checksum-verified MythicMobs `5.13.1-SNAPSHOT` input from the private
-ServerAssets repository.
+`2.0.1`, RPCharacters `2.4.0`, SimpleFactions `3.0.2`, and
+InteractibleFurniture `0.2.1` release artifacts with the shared dependency
+installer. The build also prepares a checksum-verified MythicMobs
+`5.13.1-SNAPSHOT` input from the private ServerAssets repository.
 
 At runtime, `plugin.yml` requires TLibs, SimpleFactions, MythicMobs,
-ItemsAdder, and InteractibleFurniture. The plugin code does not call ItemsAdder
-directly; the default lure is an ItemsAdder item (`ia.tfmc:lure`) placed as
-InteractibleFurniture.
+ItemsAdder, and InteractibleFurniture; RPCharacters is optional. The plugin
+code does not call ItemsAdder directly; the default lure is an ItemsAdder item
+(`ia.tfmc:lure`) placed as InteractibleFurniture.
 
 ## Guides
 

projects/Infestations/overview.md

@@ -76,15 +76,37 @@ second until they leave.
   still zero, the lure is removed and the infestation is cleared. The delay lets
   death summons join the count.
 - **Failure:** the lure is removed and the infestation returns to idle at the
-  same severity when no committed player is alive, online, or within the logout
-  grace period. A committed player who leaves the province stays in the lure and
-  takes `deserter-damage` every second, in Survival or Adventure, until
-  `/lure leave` drops them out. Coming back into the province stops that damage
-  without dropping them. `/lure leave` fails the lure when nobody committed
-  remains.
+  same severity when no committed player is alive and online, within the
+  logout grace period, or owed a death on login. A death held without a
+  character, described below, does not count. A committed player who leaves
+  the province stays in the lure and takes `deserter-damage` every second, in
+  Survival or Adventure, until `/lure leave` drops them out. Coming back into
+  the province stops that damage without dropping them. `/lure leave` fails
+  the lure when nobody committed remains.
 - **Logout:** a committed player who logs out has `logout-grace-seconds` to
-  return and remains committed. After the grace period, they are killed on
-  their next login. A committed player who dies leaves the lure.
+  return and remains committed. After the grace period, the character they
+  logged out as is killed when it is next active, at login or after a
+  character switch. If that character has died in the meantime, the death is
+  dropped and the player leaves the lure. A committed player who dies leaves
+  the lure.
+- **Other characters:** with RPCharacters, the commitment stays with the
+  character who logged out. Only that character's return ends the grace. While
+  its grace runs or its death waits, another character on the same account
+  takes no `deserter-damage`, and its death or `/lure leave` does not touch the
+  commitment. When that other character logs out, the waiting grace or death
+  keeps its character and deadline. If character data has not loaded when the
+  player logs in, the grace or death waits until a character is active.
+- **Deaths without a character:** with RPCharacters, a death owed by a player
+  whose character was not recorded, such as one saved before characters were
+  recorded, is held instead of applied, and a console warning names the
+  player and province on enable, reload, and when the grace runs out. While it
+  is held, that account takes no `deserter-damage` and gets no warnings for
+  being outside the province, and neither the death nor the account's
+  commitment keeps the lure from failing. It clears when the lure ends or when
+  that account dies or uses `/lure leave`.
+- **Without RPCharacters:** the account is the character. A recorded character
+  is ignored, so the player is killed on their next login, and any return
+  ends the grace.
 
 Players cannot break the lure, and explosions and pistons cannot move it. Lure
 furniture that does not match saved lure state is removed on enable, reload,
@@ -144,15 +166,21 @@ map data.
   and skipped.
 - **InteractibleFurniture** hosts the lure; placement, interaction, and break
   events drive the lure lifecycle. TLibs item paths identify the lure item.
+- **RPCharacters** (optional) identifies the character a committed player
+  logged out as, read at the lowest quit priority before RPCharacters unloads
+  its data, so the logout grace, deserter damage, and a death owed after the
+  grace reach only that character. Character activation ends that character's
+  grace or applies its death.
 - **Map export:** on start and whenever infestations are set, spread, cleared,
   or reloaded, the plugin writes each province's ID, severity, group, and
   display name to `MapAPI/infestation_data.json` and uploads it through the
   SimpleFactions REST server as `infestation_data`.
 
 ## Persistence and shutdown
 
-- Infestations and lure state, including committed players, logout grace, and
-  lure counters, are stored in `plugins/Infestations/Data/infestations.json`.
+- Infestations and lure state, including committed players, logout grace, the
+  character each committed player logged out as, and lure counters, are stored
+  in `plugins/Infestations/Data/infestations.json`.
 - The latest map export is `plugins/Infestations/MapAPI/infestation_data.json`.
 - When `logging` is true, spawn decisions are appended to
   `plugins/Infestations/logs/spawn.log`; `wipe-log` deletes it on each start
@@ -186,7 +214,7 @@ dependency set:
    that killing a mob that summons parasitic worms raises the remaining count.
 5. Exercise victory, a committed player leaving the province (damage until
    `/lure leave`), losing the whole party, and a logout both within and beyond
-   the grace period.
+   the grace period, including a return on another character after it.
 6. On a test server, enable `spread` with a short interval and confirm
    worsening, land spread, single water and sea hops, and group terrain limits.
 7. Confirm `MapAPI/infestation_data.json` is written and uploaded.