docs(vehicleframework): move train setup and driving notes from the README

projects/VehicleFramework/docs/configuration.md

@@ -128,7 +128,7 @@ The component key is the type. A vehicle has one of each type. `steering` is not
 
 Shared component fields: `health`, `repair-time` (ticks), `damage-chance` (0 to 1), `alias`, `fatal`, `vfx`, `armor`, `role`, and an optional `damage` overlay. Damage numbers are multipliers for a hit type. With `armor` or `role` set, those templates merge and a local `damage` map overrides them. Without templates, `damage` is a list of `type(amount)` entries.
 
-Engine fields: `max` and `min` throttle (negative `min` is reverse), `speed` at full throttle, `turn-rate`, `requires-start`, `fuel`, `fuel-capacity`, `fuel-burn-rate`, and `refuel-states`. Sounds and particles on the engine play while it runs. `particle-bones` is a list of `bone.bone` vectors.
+Engine fields: `max` and `min` throttle (negative `min` is reverse), `speed` at 100% throttle (scaled linearly with throttle), `turn-rate`, `requires-start`, `fuel`, `fuel-capacity`, `fuel-burn-rate`, and `refuel-states`. Sounds and particles on the engine play while it runs. `particle-bones` is a list of `bone.bone` vectors.
 
 A geared engine uses a `gears` list. Each gear has `name`, `max`, `min`, `speed`, and `acceleration`. `start-gear` picks the initial gear.
 

projects/VehicleFramework/docs/models.md

@@ -2,7 +2,7 @@
 
 Vehicles are ModelEngine models. The plugin moves specific bones itself, so those bones must not be animated in Blockbench. Looping clips such as a spinning propeller or a moving track should be set to loop.
 
-Bone names in the model and in the vehicle YAML have to match. A skin can use a different `.bbmodel`, but every bone the config names has to exist on that model too.
+Bone names in the model and in the vehicle YAML have to match. A skin can use a different `.bbmodel`, but every bone the config names has to exist on that model too. Train bogie bones are the exception: a skin without them places the car rigid.
 
 ## Body
 
@@ -30,6 +30,8 @@ A `fixed: true` weapon does not use body and head bones. Fixed vehicles such as
 
 `behaviour.train.front-connector` and `back-connector` are bones at the couplers. The distance between a car's coupler and the next car's coupler is the spacing along the track.
 
+`behaviour.train.wheel-bones` are the frontmost and rearmost axle pivots; their positions along the model, times its scale, set where the car loses rail support. `behaviour.train.bogies` names two bogie bones, each pivoting at its bogie's centre, with the body rotator pivoting at the model's origin. Wheel animations for `wheel-diameter` are mirrored `forward` and `backward` loops of one wheel turn. See [Trains](using-trains.md#marking-a-vehicle-as-a-train).
+
 `towing.bone` is the hitch bone on the vehicle that pulls.
 
 ## Effects

projects/VehicleFramework/docs/trains.md

@@ -68,7 +68,7 @@ Track items, lay rules, and train debug logging live in [`trains.yml`](https://g
 One spline per track (no stored sections). A **stroke** is one lay with the configured layer item (`item-layer`, default `m.utils.train_track_layer`):
 
 - Left-click: **start location** (block or existing track). Click an existing end to join that track.
-- Right-click: **end location**. New track is a straight line in XZ from start to end (player look is ignored). Click within `join-distance` of an existing **end** to join: same track extends, or **two tracks link into one** if start is on one end and end is on another. Join curves from the **track** heading. Crossing the middle of a track still refuses (use the junction item for a turnout). Joins keep the direction (`+s`) of any track a train is on, so each train keeps its saved orientation: closing a loop never reverses the track, and linking two tracks reverses at most one track that has no train and is not a branch. Linking two occupied tracks start to start, or end to end, is refused. Trains saved in unloaded chunks count as occupying their track.
+- Right-click: **end location**. New track is a straight line in XZ from start to end (player look is ignored); extending an end curves from the track heading as described in [Curves](using-trains.md#curves). Click within `join-distance` of an existing **end** to join: same track extends, or **two tracks link into one** if start is on one end and end is on another. Join curves from the **track** heading. Crossing the middle of a track still refuses (use the junction item for a turnout). Joins keep the direction (`+s`) of any track a train is on, so each train keeps its saved orientation: closing a loop never reverses the track, and linking two tracks reverses at most one track that has no train and is not a branch. Linking two occupied tracks start to start, or end to end, is refused. Trains saved in unloaded chunks count as occupying their track.
 - **Creative / spectator:** the spline is saved, then displays rebake in one step. One place sound + particles at the last sample (`build` in `trains.yml`).
 - **Survival / adventure:** same save, but displays grow along the new stroke one sample every `build.interval-ticks` (default 4, five per second). Prefix rebakes so collinear runs become medium then large. Each step plays `build.sound` and particles at the new sample, and swings the main hand if `build.swing` is true. Set `build.interval-ticks` to `0` to always place instantly. Connecting two tracks or closing a loop is still instant plus one burst.
 - Remover item (`item-remover`, default `m.utils.train_track_remover`): left-click **digs** a sample (interior dig **splits** into two tracks). On a branch, digging any part of the **initial turnout lay** (stored as `turnoutS` on the junction) removes the whole turnout (junction, switch, and that stub). Digging past that initial lay uses normal dig/split rules; a longer branch extension is kept as plain track. The through stem stays. The remover refuses to dig track that a bound consist occupies, measured from each car out to its couplers. That includes a branch turnout the dig would drop because its frog ends up on a piece shorter than `min-lay-distance`. When a dig or lay rebuilds a spline, trains on it keep their world position on the new spline or pieces. A train in an unloaded chunk checks its saved spline and `s` against where it respawns, and re-finds the track under it (or unbinds if the track is gone).
@@ -79,6 +79,7 @@ One spline per track (no stored sections). A **stroke** is one lay with the conf
 - `item-switch` (default `ia.tfmc:railroad_switch`) plus `switch.offset-along` / `offset-out` / `offset-y` / `yaw-inward` / `throw-degrees` / `throw-degrees-per-second` place and animate the ItemDisplay on the through side of the frog. Chunk load respawns it at the saved pose; the entity is not persistent.
 - A junction branch still needs a 3-wide by 3-tall corridor of passable blocks. It may cross existing track (including the stem); overlapping tracks do not refuse a turnout.
 - `max-turn-degrees` (default 35) and `min-lay-distance` (default 8): refuse if the stroke is too short, or if a **join** turn (heading change from the existing end) is too sharp.
+- `curve-radius` (default 32, at least 1): bend radius for extensions and joins ([`TrackCurve`](https://github.com/TF-Minecraft/VehicleFramework/blob/main/src/main/java/net/tfminecraft/vehicleframework/tracks/TrackCurve.java)). Strokes too short for it bend tighter, down to `min-lay-distance / (2 sin(max-turn-degrees / 2))`.
 - Grade: stay **flat** as long as possible, then climb at `desired-grade-degrees` (default 6), never steeper than `max-grade-degrees` (default 10). Chat says **slope is too steep** if the end is too high for the run.
 - Clearance: a 3-wide by 3-tall corridor must be passable (air and plants are fine; solids and overlapping tracks are not).
 - Punching track in survival or adventure, and explosions (TNT, creepers, VF ammunition), mark edges broken and drop one `item-track` per newly broken edge. Creative punch and the remover dig do not drop.
@@ -115,7 +116,7 @@ On save, write at least:
 
 On load, cars use the normal vehicle spawning path. When both ends of a link exist in memory, `setChild` / `setParent` again. If the child chunk loads first, the car waits; it does not need a special global spawn.
 
-Do **not** require spawning the whole consist when one chunk loads. Accept temporary split until the other chunks load; retain occupied routes until missing links resolve. Old saves remain readable. Before downgrading to a plugin without body orientation, restore matching vehicle-data backups: an older reader cannot place a train saved facing −s correctly.
+Do **not** require spawning the whole consist when one chunk loads. Accept temporary split until the other chunks load; retain occupied routes until missing links resolve. Old saves remain readable. Before downgrading below 2.9.0 (the first release with body orientation), restore matching vehicle-data backups: an older reader cannot place a train saved facing −s correctly. See [Upgrading](using-trains.md#upgrading).
 
 ## Cargo, recorder and tickets