Fix train overruns at outer axle track ends

[ryanbarlow97]

Trains could overrun an open track end because stopping checks used each carriage centre while bogie poses extrapolated beyond the rails. Check the configured outer axle bones, including model scale, before accepting movement; stop the whole consist and reset speed/throttle when a step loses rail support.

Cars already overhanging can move back onto the track. Loop seams and connected junctions remain traversable, including wheels entering a thrown turnout before the carriage centre. Configurations without wheel-bones check bogie pivots when available and retain centre checks for rigid cars.

Companion configuration PR: https://github.com/TF-Minecraft/ServerAssets/pull/23. Requires the matching ServerAssets train YAML to check the outer axles on the stock locomotive, coal car, passenger car, and flat car. Existing server configurations are not overwritten by the plugin.

Validation: mvn -o -q clean verify passed, with 593 tests and no failures/errors. Regression coverage includes forward/reverse overrun at low and high speeds, the last coupled car, repeated pressure against the track end, recovery, scaled models, loops, branch tips, and junction entry. Six regression cases failed before the fix. In-game validation has not been performed.

Summary by CodeRabbit

• Bug Fixes
  • Trains now stop before their outer axles pass an open track end, and won’t creep beyond it while held at the endpoint.
  • Trains can drive back onto the track if a car is already overhanging.
  • Axle support is accounted for at branch tips, junctions, and loop seams, including when wheel placement is scaled.
  • Trains without wheel-bone configuration continue to use fallback track checks.

[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: 7b825ea6-93ec-4e1c-a898-84884e0b56d2

📥 Commits

Reviewing files that changed from the base of the PR and between 5bc735e and b196e20.

📒 Files selected for processing (3)

• README.md
• src/main/java/net/tfminecraft/vehicleframework/vehicles/handlers/TrainHandler.java
• src/test/java/net/tfminecraft/vehicleframework/vehicles/handlers/TrainReversePlacementTest.java

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

---

📝 Walkthrough

Walkthrough

Train placement now records missing rail support at bogie and configured wheel-bone positions. Movement checks reject steps that increase missing wheel support. Tests cover track ends, overhang recovery, scaled axle bones, loop seams, branch tips, and junctions.

Changes

Train Track-End Support

Layer / File(s)	Summary
Configure and calculate wheel support src/main/java/net/tfminecraft/vehicleframework/vehicles/handlers/TrainHandler.java	TrainHandler loads and copies configured wheel-bone names. It calculates support gaps at bogie and wheel-bone positions and records them for locomotive and car placement.
Movement validation and track-boundary behavior src/main/java/net/tfminecraft/vehicleframework/vehicles/handlers/TrainHandler.java, src/test/java/net/tfminecraft/vehicleframework/vehicles/handlers/TrainReversePlacementTest.java, README.md	Movement checks reject steps that increase missing wheel support. Tests cover stopping and recovery at track ends, scaled wheel support, loop seams, branch tips, and junctions. The README documents the checks and fallback behavior.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to b196e

The track-end checks have no identified merge-blocking issue. In-game validation remains advisable but is not evidence of a defect.

Security Architecture Review

Security architecture risk: 🔵 Low · up to b196e

The change adds a movement safeguard without an identified new security attack path. Its axle-level protection depends on matching vehicle configuration and available model bones, so some deployments may retain weaker track-end checks.

Retained concerns

• Medium · reliability · inferred: Axle-level track-end containment depends on separately installed vehicle YAML; configured bones that are unavailable are silently omitted from the support check. A code-only or mismatched rollout can therefore retain the earlier, weaker checks rather than deliver the new safeguard.

Security review details

Security Blast Radius

• inferred — A movement decision immediately affects the root locomotive and its attached consist on the routed track; the inspected path does not show new authority over unrelated vehicles, services, or data stores.

Trust Boundaries and Controls

• observed — Speed is read at the existing root-train tick entrypoint, while candidate placement passes consist-wide support and collision checks before commit. The new support check depends on configured, resolvable bone names.

Resilience and Maintainability Implications

• observed — Rejected movement restores route fields before committing placement, but the inspected evidence does not establish serialization against concurrent track or model changes.

Hardening Proposals

• proposed — Validate or visibly report unresolved configured axle bones, and verify the matching vehicle YAML is deployed before relying on outer-axle containment.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 30 functions across 2 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preventing train overruns when an outer axle reaches a track end.

Full details: Docstring Coverage

Explanation

Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 30 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{A rabbit checks the rails ahead,
And counts the wheels beneath the train.
At track ends, every axle waits,
Then rolls back safely once again.
Through loops and junctions, onward hops,
With steady paws along the line.}

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

[ryanbarlow97]

Reviewed the final-head approval and advisory comments. There are no inline findings or unresolved review threads. The rollout will install the matching four vehicle YAML files from TF-Minecraft/ServerAssets#23 together with the plugin, and verify their axle bone references and installed hashes. Missing-model fallback remains intentional for unloaded models; the README documents the weaker legacy fallback. Additional runtime diagnostics and broad docstring coverage are deferred beyond this regression fix.

Validation: all 593 local tests and clean verification passed; the final-head GitHub build passed. In-game wheel behavior still needs a player check after deployment.

[ryanbarlow97]

Published VehicleFramework 2.4.1 from merged commit a8625f6. Release verification passed all 593 tests; artifact commit, embedded version and SHA-256 verified.

Installed the JAR, five matching train configs (ServerAssets #23 and #25), and the flatbed wheel-animation correction (ServerAssets #26) on dev and main, with verified backups. Dev restarted and enabled 2.4.1 successfully; Paper finished startup and status responds. Main was not restarted or reloaded, its Paper process stayed unchanged, and status responds; files activate at its next restart. No new startup error/warning categories versus baseline. In-game driving and wheel-direction confirmation remains to be done.