Enforce configurable hand card limits per game

[XxFran10xX]

Players could draw beyond a game's intended hand size at an idle table. Add per-game hand-card-limit in games.yml: Hold'em defaults to 2 and Five-Draw to 5; omitted or nonpositive values allow unrestricted card counts.

Enforce the limit before consuming a shoe card, counting held cards and cards in flight. Blocked automatic deals finish their callback, and discarding makes room again. The cap includes all cards held by a player, including Blackjack split groups; Blackjack and free play remain uncapped by default. Existing installations need the two new settings in games.yml.

Validation:

• Reviewed the complete diff and checked whitespace.
• Java 21 PR DEV build: all 1,114 tests passed; runtime JAR validation and coverage generation passed.
• Corrected regression tests passed locally (13 tests).
• Staged the exact CI artifact and minimal config additions on TFMCDev01. Its coordinated restart loaded Games vDEV-20261001-1653, loaded configs, enabled successfully, and reached Paper Done at 2026-10-01 16:58:36 UTC.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

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: a4701307-4103-43ac-be07-a18358c87258

📥 Commits

Reviewing files that changed from the base of the PR and between e4ee4cf and 3ef9606.

📒 Files selected for processing (8)

• README.md
• src/main/java/net/tfminecraft/games/cache/Cache.java
• src/main/java/net/tfminecraft/games/loader/GamesLoader.java
• src/main/java/net/tfminecraft/games/table/TableManager.java
• src/main/resources/games.yml
• src/main/resources/messages.yml
• src/test/java/net/tfminecraft/games/loader/GamesLoaderTest.java
• src/test/java/net/tfminecraft/games/table/TableManagerHandLimitTest.java

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

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Added configurable card limits for player hands. The bundled Hold’em limit is 2 cards, and the Five-Draw limit is 5. Players are notified when they reach the limit.
  • Limits account for cards being dealt and Blackjack split groups. Omitted, zero or negative limits allow unlimited cards.
• Documentation
  • Added guidance on configuring hand card limits, including a note that existing servers must update their own game settings to apply them.

Walkthrough

The change adds per-game hand-card limits to game configuration. The loader stores these limits by game ID. Card draws check held and pending cards against the configured limit. Bundled settings, player messaging, documentation and tests are updated.

Changes

Hand-card limits

Layer / File(s)	Summary
Configure and load hand-card limits src/main/java/net/tfminecraft/games/cache/Cache.java, src/main/java/net/tfminecraft/games/loader/GamesLoader.java, src/main/resources/games.yml, src/test/java/net/tfminecraft/games/loader/GamesLoaderTest.java, README.md	The loader clears and populates the per-game limit map. Missing and negative values become 0. Bundled settings set poker to 2 and draw to 5. Documentation describes the setting and its unrestricted cases. Loader tests cover configured values, defaults and reloads.
Enforce limits during draws src/main/java/net/tfminecraft/games/table/TableManager.java, src/main/resources/messages.yml, src/test/java/net/tfminecraft/games/table/TableManagerHandLimitTest.java	Before drawing, the table manager counts held and pending cards. If a positive limit is reached, it sends hand.limit and stops the draw. Tests cover manual and automatic draws, pending cards, returned cards and unrestricted draws.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Player
  participant TableManager
  participant Cache
  participant Messages
  Player->>TableManager: Request a card draw
  TableManager->>Cache: Read limit for the game ID
  TableManager->>TableManager: Count held and pending cards
  TableManager->>Messages: Send hand.limit when the positive limit is reached
  TableManager-->>Player: Stop draw when the limit is reached

Loading

Suggested reviewers: ryanbarlow97

Merge Risk: ⚪ Minimal · up to 3ef96

This adds configurable per-game hand-card limits, enforced before a card is drawn. No actionable merge-blocking risk was identified. Normal CI and the DEV build check should still run before merge.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 3ef96

The change adds a restrictive check within existing card-draw handling without expanding player privileges. Delivery and cleanup paths support the new counting rule. Remaining uncertainty concerns runtime validation and incomplete security coverage, rather than a confirmed vulnerability.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The reviewed effect is bounded to player card eligibility at tables using the configured game ID. Configuration changes apply across matching tables, while each decision counts the requesting player's held and pending cards.

Trust Boundaries and Controls

• observed — Configuration authority remains with server configuration and administrative reload. The reload command requires games.admin.reload; ordinary player draw input reaches the eligibility check rather than a configuration-write operation.

Resilience and Maintainability Implications

• observed — Although pending cards are keyed by player UUID, a first draw creates an empty table hand entry before registering pending delivery. tableHolding recognizes empty entries, so quit handling can locate the originating table. Hand removal and table reset route through pending-card cleanup; the suspected missing-first-hand cleanup path is therefore not supported.

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

Autopilot is currently an internal CodeRabbit preview.

---

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