Bind infestation penalties and delayed spawns to character sessions

[ryanbarlow97]

Switching away from a committed character now starts that character's lure grace; returning waits for its ready session. A missing provider can no longer turn a saved character penalty into an account penalty and damage another character.

• Use TLibs 2.3.0 session start/end events and owner-checked directory snapshots; remove the RPCharacters dependency and activation/quit-ordering workaround. An outdated TLibs installation gets a clear startup error.
• Preserve saved grace/death/character fields, original deadlines, case-insensitive character UUIDs, and existing DEAD/MISSING settlement. Unknown or malformed identities remain held. Capture departures on consumer shutdown as well as provider end events.
• Keep standalone gameplay when no character identity is known; once the manager sees a provider or saved character tags, provider loss holds commitments. Untagged legacy records remain inherently ambiguous after restarting without a provider; the guide documents this limitation.
• Require readiness before placing/joining lures, recheck the exact session between penalties, and bind delayed ambient spawns to the original session and player connection. World-owned lure waves retain their existing lifecycle.

Validation: Java 21 mvn clean verify passed 169 tests, with 100% of 2,056 executable lines covered. Regression cases cover all end reasons, provider loss/arrival, A → B → A, reentrant damage, pending readiness, persisted debt ownership, standalone reconnects, and missing APIs. Runtime JAR metadata verification passed. Independent Astra review found no issues. Live Paper validation remains part of the full pinned-release lab; nothing has been deployed.

Docs: TF-Minecraft/Docs#164

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 90f1c491-e4b4-4fa4-80b2-46c6ae0ae05d

---

📥 Commits

Reviewing files that changed from the base of the PR and between f1c979a and 3220aea.

---

📒 Files selected for processing (12)

• pom.xml
• src/main/java/net/tfminecraft/infestations/Infestations.java
• src/main/java/net/tfminecraft/infestations/infestation/CharacterActivatedListener.java
• src/main/java/net/tfminecraft/infestations/infestation/InfestationManager.java
• src/main/java/net/tfminecraft/infestations/spawn/AmbientSpawnService.java
• src/main/java/net/tfminecraft/infestations/utils/Characters.java
• src/main/resources/messages.yml
• src/main/resources/plugin.yml
• src/test/java/net/tfminecraft/infestations/InfestationsLifecycleTest.java
• src/test/java/net/tfminecraft/infestations/InfestationsServicesTest.java
• src/test/java/net/tfminecraft/infestations/infestation/InfestationManagerTest.java
• src/test/java/net/tfminecraft/infestations/spawn/SpawnServicesTest.java

---

💤 Files with no reviewable changes (2)

• src/main/java/net/tfminecraft/infestations/infestation/CharacterActivatedListener.java
• src/main/resources/plugin.yml

---

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Character sessions are now used to manage infestation participation, logout grace periods and death penalties. Character-specific commitments remain separate when multiple characters share an account.
  • Players need a ready character session to join a lure when character support is available.
• Bug Fixes
  • Ambient spawns now wait for a ready character session and are cancelled if the player’s connection, location or session changes before they occur.
  • The plugin now disables itself with a clear log message if the required character support is unavailable.

Walkthrough

The plugin replaces RPCharacters integration with the shared character identity API. Infestation participation and ambient spawning now check character-session readiness and validity. Character-specific commitment handling covers session starts, ends, logout, death and shutdown.

Changes

Shared character identity and session handling

Layer / File(s)	Summary
Shared API integration and startup checks pom.xml, src/main/java/net/tfminecraft/infestations/utils/Characters.java, src/main/java/net/tfminecraft/infestations/Infestations.java, src/main/java/net/tfminecraft/infestations/infestation/CharacterActivatedListener.java, src/main/resources/plugin.yml, src/main/resources/messages.yml, src/test/java/net/tfminecraft/infestations/InfestationsLifecycleTest.java	The build uses TLibs 2.3.0 and removes the RPCharacters dependency. Character lookups use the shared API. Startup disables the plugin if the API check throws a LinkageError. The old activation listener is removed, and the lifecycle tests cover startup and character event handling.
Session-bound infestation commitments src/main/java/net/tfminecraft/infestations/infestation/InfestationManager.java, src/test/java/net/tfminecraft/infestations/InfestationsServicesTest.java, src/test/java/net/tfminecraft/infestations/infestation/InfestationManagerTest.java	InfestationManager uses character sessions to gate joining and lure placement, and to record or settle character-specific commitments. Tests cover session changes, provider availability, grace periods, death debts and stale join callbacks.
Session-aware ambient spawning src/main/java/net/tfminecraft/infestations/spawn/AmbientSpawnService.java, src/test/java/net/tfminecraft/infestations/spawn/SpawnServicesTest.java	Ambient spawning requires a ready session when the character system is available. Delayed spawns check the original player connection, province and captured session before proceeding.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant CharacterIdentity
  participant InfestationManager
  participant Characters
  CharacterIdentity->>InfestationManager: Send character session start or end event
  InfestationManager->>Characters: Check whether the session is current
  Characters-->>InfestationManager: Return current-session status
  InfestationManager->>InfestationManager: Process the matching character's return or departure

Loading

Suggested reviewers: drefvelin

---

Merge Risk: ⚪ Minimal · up to 3220a

This change ties infestation penalties and delayed ambient spawns to character sessions using the shared TLibs character API. Startup now reports a clear error when the installed TLibs is too old. No concrete defect was identified, and the change appears ready to merge with normal live-server validation.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}