Skip to content

docs: explain durable vehicle construction and recovery #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanbarlow97 merged 2 commits into from
Oct 15, 2026
Merged

docs: explain durable vehicle construction and recovery #274

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1e7e761
docs: explain durable vehicle construction and recovery
ryanbarlow97 Oct 15, 2026
e9e34e7
docs: clarify cancellation event snapshot fields
ryanbarlow97 Oct 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions projects/VFBuilders/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,24 @@ both fields. Saves made before the character was recorded load with a null
character. VFBuilders does not look up heirs. SimpleFactions treats a null
character as "resolve the account's heir, or quarantine".

Accepted construction is saved immediately. Progress is checkpointed every 30
seconds while a build is queued, and completion, cancellation and station removal
also save the queue. Interrupted shutdowns can add up to 30 seconds of repeated
building time. Snapshots replace the previous file atomically and do not remove
timer displays. If the initial save fails, construction is cancelled through the
normal material and registration-fee refund path.

A queued project's optional `outputUuid` records the vehicle created during
completion. Recovery checks VehicleFramework's stored rows, including destroyed
vehicles, before spawning another output. The output must be saved before the
station clears its job. Keep a backup of `stations.json` before upgrading; before
downgrading, resolve any projects with `outputUuid` because older VFBuilders
versions ignore that field. Accepted-start and output-recovery messages identify
the station and build in the server log. This recovery protects saved jobs; it
does not reconstruct jobs that were never saved. Inventory, registration fees
and the station file are separate stores, so a process failure during their
handoff can still require staff reconciliation.

### API for other plugins

[`BeginVehicleConstructionEvent`](https://github.com/TF-Minecraft/VFBuilders/blob/main/src/main/java/net/tfminecraft/vfbuilders/events/BeginVehicleConstructionEvent.java),
Expand All @@ -77,6 +95,9 @@ expose `UUID getConstructorCharacterId()`. The construct and cancel events
also expose the account as `getConstructorUuid()`. The begin event carries the
`Player`.

Cancellation listeners must read the blueprint and constructor from the event's
getters; the station's queued job has already been cleared durably.

[`ConstructionFreeze`](https://github.com/TF-Minecraft/VFBuilders/blob/main/src/main/java/net/tfminecraft/vfbuilders/api/ConstructionFreeze.java)
providers are registered with Bukkit's `ServicesManager`. Each second, every
station still counting down calls
Expand Down