<?xml version="1.0" encoding="utf-8"?>
<!--
  ═══════════════════════════════════════════════════════════════════════════════
  EntityV6WheelDrive — XML Reference  [ENGLISH]
  Multi-axle vehicle system: 4, 6 and 8 wheels
  ═══════════════════════════════════════════════════════════════════════════════

  WHAT IT DOES
  ════════════
  EntityV6WheelDrive is a custom EntityDriveable class that drives vehicles
  with 2, 3 or 4 axles (4, 6 or 8 wheels). It extends the base vehicle class
  with three independent systems:

	1. MULTI-AXLE STEERING
	   Axle 1 (front) steers normally.
	   Axle 2 (mid-front) can steer softly in the same direction (factor).
	   Axle 3 (mid-rear) can counter-steer, fading out at high speed.
	   Axle 4 (rear) can counter-steer with its own independent max angle.

	2. TORQUE-BIASED DIFFERENTIAL
	   Distributes motor torque left/right per turn direction.
	   A lockable diff key toggles equal torque on both sides.

	3. PER-AXLE BRAKE AND SIDE FRICTION
	   Each axle can have an independent brake multiplier and side grip level.

  HOW TO USE IT
  ══════════════
  Two separate files are required:

  1) entityclasses.xml  — declare the entity class, prefab and entity-level properties:

	<append xpath="/entity_classes">
	  <entity_class name="myTruck">
		<property name="Class"     value="WitosRoot.EntityV6WheelDrive,suspension"/>
		<property name="Tags"      value="vehicle"/>
		<property name="Parent"    value="Cars"/>
		<property name="Prefab"    value="#@modfolder:Resources/myTruck.unity3d?myTruck"/>
		<property name="ModelType" value="Standard"/>
		<!-- ... other entity-level properties ... -->
	  </entity_class>
	</append>

  2) vehicles.xml  — declare the driving behavior properties (same name as entity_class):

	<append xpath="/vehicles">
	  <vehicle name="myTruck">
		<properties>
		  <property name="steerAxle2Factor" value="0.15"/>
		  <!-- ... rest of driving properties ... -->
		</properties>
	  </vehicle>
	</append>

  The <vehicle name> MUST match the <entity_class name> exactly.
  All driving properties are optional — every one has a sensible default.

  ═══════════════════════════════════════════════════════════════════════════════
  UNITY PREFAB — WHEEL ARRAY ORDER  (CRITICAL)
  ═══════════════════════════════════════════════════════════════════════════════

  Wheels must be assigned to the vehicle's wheels array in this exact order:

	Index 0 → Left  wheel, Axle 1  (front-left)
	Index 1 → Right wheel, Axle 1  (front-right)
	Index 2 → Left  wheel, Axle 2  (mid-front-left   / rear-left  on 4-wheel)
	Index 3 → Right wheel, Axle 2  (mid-front-right  / rear-right on 4-wheel)
	Index 4 → Left  wheel, Axle 3  (mid-rear-left)   ← 6-wheel minimum
	Index 5 → Right wheel, Axle 3  (mid-rear-right)
	Index 6 → Left  wheel, Axle 4  (rear-left)       ← 8-wheel only
	Index 7 → Right wheel, Axle 4  (rear-right)

  Rule: always LEFT before RIGHT, front to rear.
  Even-indexed wheels (0, 2, 4, 6) are left. Odd-indexed (1, 3, 5, 7) are right.

  ═══════════════════════════════════════════════════════════════════════════════
  STEERING SYSTEM  — how each axle steers
  ═══════════════════════════════════════════════════════════════════════════════

  ┌────────┬──────────────┬──────────────────────────────────────────────────┐
  │ Axle   │ Wheels       │ Behavior                                         │
  ├────────┼──────────────┼──────────────────────────────────────────────────┤
  │ Axle 1 │ [0] and [1]  │ Full front steer (= wheelDir, always)            │
  │ Axle 2 │ [2] and [3]  │ Same direction × steerAxle2Factor                │
  │        │              │ (0 = no steer,  1 = same as front)               │
  │ Axle 3 │ [4] and [5]  │ Counter-steer × steerAxle3CounterMax             │
  │        │              │ fades to zero above steerRearFadeSpeed m/s       │
  │ Axle 4 │ [6] and [7]  │ Counter-steer × steerAxle4CounterMax             │
  │        │              │ same speed fade as axle 3                        │
  └────────┴──────────────┴──────────────────────────────────────────────────┘

  Rear steer fade formula:
	rearSteerBlend = 1 − clamp01(speed_m_s / steerRearFadeSpeed)
	At speed = 0       → blend = 1.0 (full rear steer, tight low-speed turns)
	At speed = fadeMax → blend = 0.0 (no rear steer, stable highway driving)

  ═══════════════════════════════════════════════════════════════════════════════
  DIFFERENTIAL BIAS  — how torque is split left/right
  ═══════════════════════════════════════════════════════════════════════════════

  leftBias  = 1 + diffBias × steerNorm
  rightBias = 1 − diffBias × steerNorm

  steerNorm is the normalized steering angle (−1 left … +1 right).

  When turning right (steerNorm > 0):
	Left  wheel (outer on right turn) gets MORE torque.
	Right wheel (inner)               gets LESS torque.
  This simulates a torque-sensitive differential that pushes the vehicle
  through the turn rather than fighting it.

  When diffLocked = ON (key pressed), bias = 0 → equal torque both sides.

  ═══════════════════════════════════════════════════════════════════════════════
-->

<entityv6wheeldrive_reference>

  <!-- ══════════════════════════════════════════════════════════════════════
	   EXAMPLE 1 — 4-WHEEL VEHICLE  (standard car / light truck)
	   Axles used: 1 and 2. Axle 2 is the rear axle, no steering.
	   ══════════════════════════════════════════════════════════════════════ -->

  <!-- entityclasses.xml -->
  <entity_class name="myLightTruck_4wheel">
	<property name="Class"     value="WitosRoot.EntityV6WheelDrive,suspension"/>
	<property name="Tags"      value="vehicle"/>
	<property name="Parent"    value="Cars"/>
	<property name="Prefab"    value="#@modfolder:Resources/myLightTruck.unity3d?myLightTruck"/>
	<property name="ModelType" value="Standard"/>
  </entity_class>

  <!-- vehicles.xml -->
  <vehicle name="myLightTruck_4wheel">
	<properties>
	  <!-- STEERING -->
	  <!-- Axle 2 (rear) does NOT steer — normal rear-wheel-drive behavior -->
	  <property name="steerAxle2Factor"      value="0"/>
	  <!-- Axle 3 and 4 don't exist on a 4-wheel vehicle, these are ignored -->
	  <property name="steerAxle3CounterMax"  value="0"/>
	  <property name="steerAxle4CounterMax"  value="0"/>
	  <!-- Speed at which any rear steer fades — irrelevant here but harmless -->
	  <property name="steerRearFadeSpeed"    value="8"/>

	  <!-- DIFFERENTIAL -->
	  <!-- Slight torque bias for sporty feel — inner/outer wheel split on turns -->
	  <property name="diffBias"              value="0.2"/>
	  <!-- Diff lock disabled — use 0 bias instead -->
	  <property name="diffLockEnabled"       value="false"/>
	  <property name="diffLockKey"           value="L"/>

	  <!-- BRAKE PER AXLE -->
	  <!-- Front brakes slightly stronger than rear (realistic) -->
	  <property name="brakeAxle1"            value="1.0"/>
	  <property name="brakeAxle2"            value="0.75"/>

	  <!-- SIDE FRICTION PER AXLE -->
	  <!-- Equal grip front and rear -->
	  <property name="sideFrictionAxle1"     value="1.0"/>
	  <property name="sideFrictionAxle2"     value="1.0"/>
	</properties>
  </vehicle>

  <!--
	Unity wheels array for this vehicle:
	  [0] Front-Left   WheelCollider
	  [1] Front-Right  WheelCollider
	  [2] Rear-Left    WheelCollider
	  [3] Rear-Right   WheelCollider
  -->


  <!-- ══════════════════════════════════════════════════════════════════════
	   EXAMPLE 2 — 6-WHEEL VEHICLE  (military truck / 6×6)
	   Axles: front (1), mid (2), rear (3).
	   Axle 2 steers slightly same direction as front.
	   Axle 3 counter-steers at low speed for tight turns.
	   ══════════════════════════════════════════════════════════════════════ -->

  <!-- entityclasses.xml -->
  <entity_class name="myMilitaryTruck_6wheel">
	<property name="Class"     value="WitosRoot.EntityV6WheelDrive,suspension"/>
	<property name="Tags"      value="vehicle"/>
	<property name="Parent"    value="Cars"/>
	<property name="Prefab"    value="#@modfolder:Resources/myMilitaryTruck.unity3d?myMilitaryTruck"/>
	<property name="ModelType" value="Standard"/>
  </entity_class>

  <!-- vehicles.xml -->
  <vehicle name="myMilitaryTruck_6wheel">
	<properties>
	  <!-- STEERING -->
	  <!-- Axle 2 (mid) turns slightly the same way as the front — helps tracking -->
	  <property name="steerAxle2Factor"      value="0.15"/>
	  <!-- Axle 3 (rear) counter-steers up to 0.5× the front angle at low speed -->
	  <property name="steerAxle3CounterMax"  value="0.5"/>
	  <!-- Axle 4 not present, ignored -->
	  <property name="steerAxle4CounterMax"  value="0"/>
	  <!-- Rear steer fades out completely by 10 m/s (≈36 km/h) -->
	  <property name="steerRearFadeSpeed"    value="10"/>

	  <!-- DIFFERENTIAL -->
	  <!-- Moderate bias — helps the heavy truck swing through turns -->
	  <property name="diffBias"              value="0.3"/>
	  <!-- Diff lock for off-road — press L to toggle equal torque both sides -->
	  <property name="diffLockEnabled"       value="true"/>
	  <property name="diffLockKey"           value="L"/>

	  <!-- BRAKE PER AXLE -->
	  <!-- Front brakes hardest, rear two axles moderate -->
	  <property name="brakeAxle1"            value="1.0"/>
	  <property name="brakeAxle2"            value="0.85"/>
	  <property name="brakeAxle3"            value="0.85"/>

	  <!-- SIDE FRICTION PER AXLE -->
	  <!-- Front has full grip; mid and rear slightly reduced (dual tires) -->
	  <property name="sideFrictionAxle1"     value="1.0"/>
	  <property name="sideFrictionAxle2"     value="0.9"/>
	  <property name="sideFrictionAxle3"     value="0.9"/>
	</properties>
  </vehicle>

  <!--
	Unity wheels array for this vehicle:
	  [0] Front-Left     WheelCollider
	  [1] Front-Right    WheelCollider
	  [2] Mid-Left       WheelCollider
	  [3] Mid-Right      WheelCollider
	  [4] Rear-Left      WheelCollider
	  [5] Rear-Right     WheelCollider
  -->


  <!-- ══════════════════════════════════════════════════════════════════════
	   EXAMPLE 3 — 8-WHEEL VEHICLE  (heavy transporter / armored carrier)
	   Axles: 1 (front), 2 (mid-front), 3 (mid-rear), 4 (rear).
	   All four axles have independent steering and brake control.
	   ══════════════════════════════════════════════════════════════════════ -->

  <!-- entityclasses.xml -->
  <entity_class name="myHeavyCarrier_8wheel">
	<property name="Class"     value="WitosRoot.EntityV6WheelDrive,suspension"/>
	<property name="Tags"      value="vehicle"/>
	<property name="Parent"    value="Cars"/>
	<property name="Prefab"    value="#@modfolder:Resources/myHeavyCarrier.unity3d?myHeavyCarrier"/>
	<property name="ModelType" value="Standard"/>
  </entity_class>

  <!-- vehicles.xml -->
  <vehicle name="myHeavyCarrier_8wheel">
	<properties>
	  <!-- STEERING -->
	  <!-- Axle 2 (mid-front) steers same direction, 20% of front angle -->
	  <property name="steerAxle2Factor"      value="0.20"/>
	  <!-- Axle 3 (mid-rear) counter-steers up to 50% of front angle at low speed -->
	  <property name="steerAxle3CounterMax"  value="0.5"/>
	  <!-- Axle 4 (rear) counter-steers more aggressively for tight turns -->
	  <property name="steerAxle4CounterMax"  value="0.7"/>
	  <!-- Rear steer fades out by 8 m/s — keeps stability at speed -->
	  <property name="steerRearFadeSpeed"    value="8"/>

	  <!-- DIFFERENTIAL -->
	  <!-- Strong torque bias — helps massive vehicle pivot on low-speed maneuvers -->
	  <property name="diffBias"              value="0.4"/>
	  <!-- Diff lock available — essential for off-road heavy hauling -->
	  <property name="diffLockEnabled"       value="true"/>
	  <property name="diffLockKey"           value="L"/>

	  <!-- BRAKE PER AXLE -->
	  <!-- All four axles brake, front two slightly harder -->
	  <property name="brakeAxle1"            value="1.0"/>
	  <property name="brakeAxle2"            value="0.9"/>
	  <property name="brakeAxle3"            value="0.8"/>
	  <property name="brakeAxle4"            value="0.8"/>

	  <!-- SIDE FRICTION PER AXLE -->
	  <!-- Front has full grip; rear axles slightly reduced for realistic push -->
	  <property name="sideFrictionAxle1"     value="1.0"/>
	  <property name="sideFrictionAxle2"     value="0.95"/>
	  <property name="sideFrictionAxle3"     value="0.85"/>
	  <property name="sideFrictionAxle4"     value="0.85"/>
	</properties>
  </vehicle>

  <!--
	Unity wheels array for this vehicle:
	  [0] Front-Left       WheelCollider
	  [1] Front-Right      WheelCollider
	  [2] Mid-Front-Left   WheelCollider
	  [3] Mid-Front-Right  WheelCollider
	  [4] Mid-Rear-Left    WheelCollider
	  [5] Mid-Rear-Right   WheelCollider
	  [6] Rear-Left        WheelCollider
	  [7] Rear-Right       WheelCollider
  -->


  <!-- ══════════════════════════════════════════════════════════════════════
	   EXAMPLE 4 — 6-WHEEL CRANE / PIVOT MOVER  (extreme low-speed turns)
	   Maximum counter-steer on rear axle, very low fade speed.
	   ══════════════════════════════════════════════════════════════════════ -->

  <!-- entityclasses.xml -->
  <entity_class name="myCrane_6wheel">
	<property name="Class"     value="WitosRoot.EntityV6WheelDrive,suspension"/>
	<property name="Tags"      value="vehicle"/>
	<property name="Parent"    value="Cars"/>
	<property name="Prefab"    value="#@modfolder:Resources/myCrane.unity3d?myCrane"/>
	<property name="ModelType" value="Standard"/>
  </entity_class>

  <!-- vehicles.xml -->
  <vehicle name="myCrane_6wheel">
	<properties>
	  <!-- STEERING -->
	  <!-- Mid axle steers same way as front (tag-axle style) -->
	  <property name="steerAxle2Factor"      value="0.30"/>
	  <!-- Rear axle counter-steers at full intensity — very tight pivot -->
	  <property name="steerAxle3CounterMax"  value="1.0"/>
	  <!-- Rear steer fades by just 3 m/s — almost instantly at any speed -->
	  <property name="steerRearFadeSpeed"    value="3"/>

	  <!-- DIFFERENTIAL -->
	  <!-- No bias — crane drives straight or pivots, not carving turns -->
	  <property name="diffBias"              value="0"/>
	  <property name="diffLockEnabled"       value="true"/>
	  <property name="diffLockKey"           value="L"/>

	  <!-- BRAKE PER AXLE -->
	  <!-- All axles brake equally — predictable stops when loaded -->
	  <property name="brakeAxle1"            value="1.0"/>
	  <property name="brakeAxle2"            value="1.0"/>
	  <property name="brakeAxle3"            value="1.0"/>

	  <!-- SIDE FRICTION PER AXLE -->
	  <!-- High side friction everywhere — no lateral drift under load -->
	  <property name="sideFrictionAxle1"     value="1.2"/>
	  <property name="sideFrictionAxle2"     value="1.2"/>
	  <property name="sideFrictionAxle3"     value="1.2"/>
	</properties>
  </vehicle>


  <!-- ══════════════════════════════════════════════════════════════════════
	   COMPLETE PROPERTY REFERENCE
	   ══════════════════════════════════════════════════════════════════════ -->

  <!--
  ┌───────────────────────────┬────────┬─────────┬──────────────────────────────────────────────────────────────────────────┐
  │ Property                  │ Type   │ Default │ Description                                                              │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ STEERING                  │        │         │                                                                          │
  │ steerAxle2Factor          │ float  │ 0.15    │ Fraction of front steer applied to axle 2 in the SAME direction.        │
  │                           │        │         │ 0 = axle 2 does not steer.  1 = steers as much as the front.            │
  │                           │        │         │ Typical: 0.10–0.25.                                                     │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ steerAxle3CounterMax      │ float  │ 0.5     │ Maximum counter-steer fraction for axle 3 (at low speed).               │
  │                           │        │         │ Negative direction of front steer × this factor × speed blend.          │
  │                           │        │         │ 0 = no counter-steer.  1 = full mirror of front steer.                  │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ steerAxle4CounterMax      │ float  │ 0.7     │ Same as above but for axle 4 (8-wheel vehicles only).                   │
  │                           │        │         │ Typically higher than axle 3 — rear axle pivots more aggressively.      │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ steerRearFadeSpeed        │ float  │ 8.0     │ Speed in m/s at which rear/counter steering fades completely to zero.   │
  │                           │        │         │ Applies to both axle 3 and axle 4.                                      │
  │                           │        │         │ 3 = fades almost instantly.  15 = fades slowly.                         │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ DIFFERENTIAL              │        │         │                                                                          │
  │ diffBias                  │ float  │ 0.0     │ Torque bias toward outer wheel when turning. Range: 0.0–1.0.            │
  │                           │        │         │ 0 = equal torque both sides (open diff).                                │
  │                           │        │         │ 0.3 = moderate sport bias.  0.6 = aggressive pivot.                     │
  │                           │        │         │ Automatically zeroed when diff lock is active.                          │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ diffLockEnabled           │ bool   │ false   │ Enables the diff lock toggle key.                                       │
  │                           │        │         │ When locked: equal torque both sides, ignores diffBias.                 │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ diffLockKey               │KeyCode │ L       │ Key to toggle the diff lock on/off. Any Unity KeyCode name.             │
  │                           │        │         │ Lock state is logged to console on each toggle.                         │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ BRAKE PER AXLE            │        │         │                                                                          │
  │ brakeAxle1                │ float  │ 1.0     │ Brake torque multiplier for axle 1. Range: 0.0–1.0.                    │
  │ brakeAxle2                │ float  │ 1.0     │ Brake torque multiplier for axle 2.                                     │
  │ brakeAxle3                │ float  │ 1.0     │ Brake torque multiplier for axle 3. Ignored on 4-wheel vehicles.        │
  │ brakeAxle4                │ float  │ 1.0     │ Brake torque multiplier for axle 4. Ignored unless 8 wheels present.    │
  │                           │        │         │ 0 = no braking on that axle.  1 = full brake torque.                   │
  ├───────────────────────────┼────────┼─────────┼──────────────────────────────────────────────────────────────────────────┤
  │ SIDE FRICTION PER AXLE    │        │         │                                                                          │
  │ sideFrictionAxle1         │ float  │ 1.0     │ Sideways grip multiplier for axle 1. Range: 0.0 and above.             │
  │ sideFrictionAxle2         │ float  │ 1.0     │ Sideways grip multiplier for axle 2.                                    │
  │ sideFrictionAxle3         │ float  │ 1.0     │ Sideways grip multiplier for axle 3.                                    │
  │ sideFrictionAxle4         │ float  │ 1.0     │ Sideways grip multiplier for axle 4.                                    │
  │                           │        │         │ Values > 1 increase grip beyond base. < 1 makes the axle slippery.     │
  │                           │        │         │ Note: on loose surfaces the engine automatically scales side            │
  │                           │        │         │ friction down to 33% — these multipliers stack on top of that.         │
  └───────────────────────────┴────────┴─────────┴──────────────────────────────────────────────────────────────────────────┘
  -->


  <!-- ══════════════════════════════════════════════════════════════════════
	   NOTES & TIPS
	   ══════════════════════════════════════════════════════════════════════

  WHEEL COUNT
  ● The class name says "V6" but it fully supports 4, 6 and 8 wheels.
  ● The code checks how many wheels are in the array and skips axles that
	have no wheels — you never need to set unused-axle properties.

  WHEEL ARRAY ORDER
  ● Wheels MUST be assigned left-before-right, front-to-rear in Unity.
	Getting this wrong causes crossed steering (left wheel turns right, etc).
  ● Even index = left wheel. Odd index = right wheel.
  ● Axle number = floor(index / 2) + 1.

  STEERING DESIGN GUIDE
  ● For a standard car/truck (4 wheels): set steerAxle2Factor=0.
	The rear axle never steers — classic behavior.
  ● For a 6-wheel truck: steerAxle2Factor 0.1–0.2 improves straight tracking.
	steerAxle3CounterMax 0.4–0.6 gives tight low-speed turns.
  ● For an 8-wheel carrier: use both axle3 and axle4 counter-steer.
	Axle 4 (rear) can be more aggressive since it is furthest from the pivot.
  ● steerRearFadeSpeed: lower = rear steer disappears sooner (safer at speed).
	Trucks: 8–12 m/s.  Cranes/special vehicles: 3–5 m/s.

  DIFFERENTIAL BIAS
  ● diffBias=0 is a perfectly open differential — both sides always equal.
  ● diffBias=0.2–0.3 feels sporty and helps the vehicle turn-in.
  ● diffBias=0.5+ is aggressive — good for pivoting heavy equipment.
  ● When diffLocked=ON the bias is ignored. Use diff lock on off-road or
	when one wheel lifts off the ground.
  ● diffLockEnabled=false hides the key binding — use it on simple vehicles.

  BRAKE BALANCE
  ● brakeAxle1=1.0 + brakeAxle2=0.7 is a realistic front-heavy distribution.
  ● Setting a rear axle to 0 makes it unpowered for braking (tag axle style).
  ● All axles at 1.0 gives uniform braking — good for heavy haulers that need
	all wheels to contribute.

  SIDE FRICTION
  ● sideFriction=1.0 is the base grip from the wheel collider setup.
  ● sideFriction=0.7 on rear axles creates mild oversteer tendency.
  ● sideFriction > 1.0 is valid — gives extra lateral stability (locked wheels,
	wide tires, or special tracked-tire hybrids).
  ● On mud/loose surface (_frictionPercent < 1) the game engine automatically
	applies a 0.33× penalty to side friction before your multiplier is applied.

  ENGINE STUTTER INTEGRATION
  ● If your vehicle also uses VPVisualDamageRootByHealth with engine stutter,
	that system uses VPEngine internally and does not interfere with the
	wheel torque logic here. Both systems operate independently.

  CONSOLE LOG
  ● Every time params are first loaded (on first frame driving the vehicle),
	a line is printed:
	[EntityV6WheelDrive] Params loaded: steer=[...] diff=[...] brake=[...] sideFric=[...]
	This lets you verify the values were read correctly from XML.
  ● Diff lock toggles also print to console for quick debugging.
  -->

</entityv6wheeldrive_reference>
