<?xml version="1.0" encoding="utf-8"?>
<!--
  ═══════════════════════════════════════════════════════════════════════════════
  WitosRoot — Vehicle Transport Systems  [ENGLISH]
  VehicleTowSystem  +  VehicleCarrier
  ═══════════════════════════════════════════════════════════════════════════════

  This file documents two independent transport systems that can coexist
  on the same vehicle or be used separately:

	1. VehicleTowSystem  — physics-based hitch/tow system (trailer)
	2. VehicleCarrier    — rigid carry/landing system (flatbed, helicopter pad)

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

<transport_reference>

<!-- ═══════════════════════════════════════════════════════════════════════════
	 PART 1 — VehicleTowSystem
	 Physics-based towing with ConfigurableJoint, rope, magnet, aerial mode
	 ═══════════════════════════════════════════════════════════════════════════

	 HOW IT WORKS
	 ────────────
	 Press the hitch key (default H) while driving to toggle the hitch.
	 The system searches for the nearest vehicle marked Towable=true within
	 the search radius. If found, the trailer smoothly approaches the hitch
	 point and connects with a Unity ConfigurableJoint, providing real
	 inertia, sway and wheel friction.

	 If TowHitchRope=true is set, pressing H first deploys a rope/cable.
	 Press H again when the rope tip is near a trailer to attach it.
	 Press H a third time to detach and retract the rope.

	 UNITY PREFAB — NAMED EMPTY OBJECTS
	 ────────────────────────────────────
	 Instead of using XML offsets you can place empty GameObjects in your
	 prefab with these exact names. The system searches the entire hierarchy.
	 If not found, it falls back to the XML offset values.

	   Tractor  →  TowHitch        (empty at the rear hitch ball)
	   Trailer  →  TowableHitch    (empty at the front coupling hook)
	   Magnet   →  TowMagnet       (optional, tip of the rope/cable)

	 ═══════════════════════════════════════════════════════════════════════════
	 TRACTOR VEHICLE  (the vehicle doing the towing)
	 ═══════════════════════════════════════════════════════════════════════════ -->

  <vehicle name="myTractor_example">

	<!-- ── REQUIRED ──────────────────────────────────────────────────────── -->

	<!-- Enables the hitch system on this vehicle. REQUIRED. -->
	<property name="TowHitch"               value="true"/>

	<!-- ── HITCH POINT ──────────────────────────────────────────────────── -->

	<!-- Local offset of the hitch point from the vehicle Physics center.
		 Used only if no empty object named TowHitch exists in the prefab.
		 Format: X, Y, Z  (meters, local Physics transform space)
		 X=0 centered | Y negative = downward | Z negative = rearward -->
	<property name="TowHitchOffset"         value="0,-0.3,-2.5"/>

	<!-- ── INPUT ────────────────────────────────────────────────────────── -->

	<!-- Key used to hitch/unhitch. Any Unity KeyCode name.
		 Examples: H, G, T, F, JoystickButton0
		 Default: H -->
	<property name="TowHitchKey"            value="H"/>

	<!-- ── MOD REQUIREMENT ──────────────────────────────────────────────── -->

	<!-- Name of a vehicle mod that must be installed for the hitch to work.
		 If empty or omitted the hitch is always available.
		 If set and the mod is missing, a notification is shown to the driver. -->
	<property name="TowHitchMod"            value="modTowHitch"/>

	<!-- ── SEARCH & APPROACH ────────────────────────────────────────────── -->

	<!-- Search radius in meters from the TowHitch point.
		 The trailer must be within this distance to attach.
		 Default: 5.0 -->
	<property name="TowHitchSearchRadius"   value="4.5"/>

	<!-- Speed (m/s) at which the trailer slides toward the hitch
		 before the joint is created. Lower = slower, more cinematic.
		 Default: 3.0 -->
	<property name="TowHitchApproachSpeed"  value="3.0"/>

	<!-- ── JOINT PHYSICS ────────────────────────────────────────────────── -->

	<!-- Joint stiffness (spring force).
		 Higher = stiffer connection, less trailer lag.
		 Lower  = softer, more "floating" trailer.
		 Default: 2000 -->
	<property name="TowHitchSpring"         value="2000"/>

	<!-- Joint damping. Reduces oscillations.
		 Increase if the trailer vibrates excessively.
		 Default: 200 -->
	<property name="TowHitchDamper"         value="200"/>

	<!-- Maximum force the joint can apply.
		 Limits how hard the trailer can pull the tractor on slopes/braking.
		 Default: 4000 -->
	<property name="TowHitchMaxForce"       value="4000"/>

	<!-- Maximum angular limit of the hitch in degrees (yaw/pitch).
		 45° allows tight turns. 30° is more rigid.
		 Default: 45 -->
	<property name="TowHitchMaxAngle"       value="45"/>

	<!-- Maximum roll (lateral tilt) limit in degrees.
		 Controls how much the trailer can tilt sideways over bumps.
		 5–10 = very stiff | 15 = realistic | 25–40 = very loose.
		 Set to 0 to allow free roll (no limit).
		 Default: 15 -->
	<property name="TowHitchRollLimit"      value="15"/>

	<!-- Side sway damping of the trailer angular velocity each frame.
		 0.0  = infinite free sway.
		 0.08 = realistic soft damping.
		 0.15 = very stable, almost no sway.
		 Default: 0.08 -->
	<property name="TowHitchSwayDamping"    value="0.08"/>

	<!-- Lateral wheel stiffness of the trailer while attached.
		 1.0 = full grip (trailer follows exact path of tractor).
		 0.6 = some realistic lateral slip.
		 0.3 = very slippery wheels.
		 Default: 0.6 -->
	<property name="TowHitchWheelFriction"  value="0.6"/>

	<!-- ── ROPE / CABLE SYSTEM ──────────────────────────────────────────── -->

	<!-- Enables the deployable rope/cable visual system.
		 When true, pressing H deploys the rope first. A second press while
		 the rope tip is near a trailer attaches it. A third press detaches.
		 Default: false (direct hitch without rope) -->
	<property name="TowHitchRope"            value="true"/>

	<!-- Number of segments in the rope catenary simulation.
		 More segments = smoother curve but slightly more CPU.
		 Default: 16 -->
	<property name="TowHitchRopeSegments"    value="16"/>

	<!-- Sag factor of the rope curve. Higher = more drooping.
		 Default: 1.2 -->
	<property name="TowHitchRopeSag"         value="1.2"/>

	<!-- Maximum length the rope deploys to (meters).
		 Also used as the hanging distance in aerial tow mode.
		 Default: 4.0 -->
	<property name="TowHitchRopeDeployLength" value="4.0"/>

	<!-- Speed at which the rope tip descends when deploying (m/s).
		 Default: 2.0 -->
	<property name="TowHitchRopeDescendSpeed" value="2.0"/>

	<!-- Visual width of the rope line renderer (meters).
		 Default: 0.03 -->
	<property name="TowHitchRopeWidth"        value="0.03"/>

	<!-- Lateral swing amplitude of the rope tip while deploying.
		 0 = no swing | 0.2 = gentle pendulum swing.
		 Default: 0.2 -->
	<property name="TowHitchRopeSwing"        value="0.2"/>

	<!-- Color of the rope line renderer (R,G,B — each 0.0 to 1.0).
		 Default: 0.15,0.15,0.15 (dark grey) -->
	<property name="TowHitchRopeColor"        value="0.15,0.15,0.15"/>

	<!-- ── MAGNET (rope tip) ─────────────────────────────────────────────── -->

	<!-- Visual size of the magnet sphere at the rope tip (meters).
		 Set to 0 to hide the magnet entirely.
		 Default: 0.25 -->
	<property name="TowHitchMagnetSize"       value="0.25"/>

	<!-- Visual weight/scale of the magnet (affects proportions only).
		 Default: 20 -->
	<property name="TowHitchMagnetWeight"     value="20"/>

	<!-- Position along the rope (0.0 = hitch origin, 1.0 = tip)
		 where the magnet is placed. Keep at 1.0 for tip.
		 Default: 1.0 -->
	<property name="TowHitchMagnetRopeT"      value="1.0"/>

	<!-- Euler rotation offset of the magnet visual (X,Y,Z degrees).
		 Useful if the magnet mesh faces the wrong direction.
		 Default: 0,0,0 -->
	<property name="TowHitchMagnetRotation"   value="0,0,0"/>

	<!-- Name of the child GameObject in the prefab to use as magnet visual.
		 If found, overrides the procedural sphere.
		 Default: TowMagnet -->
	<property name="TowHitchMagnetName"       value="TowMagnet"/>

	<!-- Color of the procedural magnet sphere (R,G,B).
		 Default: 0.3,0.3,0.35 (dark blue-grey) -->
	<property name="TowHitchMagnetColor"      value="0.3,0.3,0.35"/>

	<!-- ── AERIAL TOW (helicopter mode) ─────────────────────────────────── -->

	<!-- Enables aerial tow mode. When true the trailer hangs below the
		 tractor (e.g. helicopter lifting a vehicle) instead of being
		 pushed on the ground. Requires TowHitchRope=true.
		 Default: false -->
	<property name="TowHitchAerial"           value="false"/>

	<!-- Maximum swing angle (degrees) allowed for the hanging trailer
		 in aerial mode. Larger = more pendulum freedom.
		 Default: 60 -->
	<property name="TowHitchAerialAngle"      value="60"/>

  </vehicle>

<!-- ═══════════════════════════════════════════════════════════════════════════
	 TRAILER VEHICLE  (the vehicle being towed)
	 ═══════════════════════════════════════════════════════════════════════════ -->

  <vehicle name="myTrailer_example">

	<!-- Marks this vehicle as towable.
		 Without this the tow system will ignore it even if nearby. REQUIRED. -->
	<property name="Towable"                value="true"/>

	<!-- Local offset of the coupling point on the trailer.
		 Used only if no empty object named TowableHitch exists in the prefab.
		 Format: X, Y, Z  (meters, local Physics transform space)
		 X=0 centered | Y positive = upward | Z positive = forward -->
	<property name="TowableHitchOffset"     value="0,0.3,1.8"/>

	<!-- Mass scale applied to the trailer Rigidbody while attached.
		 Temporarily reduces effective mass so the tractor doesn't feel
		 the full weight during driving.
		 0.05 = almost weightless | 0.15 = light | 0.30 = still quite heavy.
		 The original mass is restored automatically when detached.
		 Default: 0.15 -->
	<property name="TowableMassScale"       value="0.15"/>

  </vehicle>


<!-- ═══════════════════════════════════════════════════════════════════════════
	 PART 2 — VehicleCarrier
	 Rigid carry system: flatbed trucks, helicopter landing pads, carriers
	 ═══════════════════════════════════════════════════════════════════════════

	 HOW IT WORKS
	 ────────────
	 The carrier vehicle has a trigger zone defined by a BoxCollider named
	 exactly "Carrier" in the Unity prefab. When a player exits a vehicle
	 that is inside this zone (or the vehicle drives/lands onto the platform),
	 the system automatically freezes the cargo and locks it to the carrier.
	 No XML properties are needed on the carrier — just the Unity BoxCollider.

	 The cargo vehicle is automatically released when a player enters and
	 drives it away, or when the carrier is destroyed.

	 UNITY PREFAB — CARRIER ZONE
	 ────────────────────────────
	 Add a BoxCollider to any child object of your carrier vehicle and name
	 it exactly "Carrier". This collider defines the snap zone:

	   CarrierRoot
	   └── Carrier        ← BoxCollider (isTrigger not required, just enabled)
							 Size it to cover the platform/deck area.

	 The system searches the entire hierarchy so the collider can be placed
	 under any parent node (Physics, M, GameObject, etc.).

	 CARGO BEHAVIOR WHILE CARRIED
	 ─────────────────────────────
	 While a vehicle is carried:
	 - Its Rigidbody is frozen (kinematic, no gravity, no collision).
	 - Its wheels and colliders are disabled.
	 - Its engine is turned off.
	 - It moves and rotates rigidly with the carrier each frame.
	 - All these are restored automatically when released.

	 MULTIPLAYER
	 ────────────
	 The system is fully server-authoritative. The server assigns cargo,
	 broadcasts state to all clients, and handles late-joining clients
	 via a state sync request. Sequence numbers prevent out-of-order updates.

	 CARGO VEHICLE — NO XML REQUIRED
	 ─────────────────────────────────
	 Any vehicle that is physically inside the Carrier BoxCollider zone when
	 a player exits it will be picked up automatically. No XML configuration
	 is needed on the cargo vehicle.

	 However, if you want to PREVENT a specific vehicle from ever being
	 picked up (e.g. a parked car that happens to be nearby), there is
	 currently no exclude property — rely on correct BoxCollider sizing. -->


<!-- ═══════════════════════════════════════════════════════════════════════════
	 QUICK REFERENCE TABLE — VehicleTowSystem
	 ═══════════════════════════════════════════════════════════════════════════

  TRACTOR PROPERTIES
  ┌─────────────────────────────┬────────┬─────────────┬──────────────────────┐
  │ Property                    │ Type   │ Default     │ Notes                │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ REQUIRED                    │        │             │                      │
  │ TowHitch                    │ bool   │ —           │ REQUIRED on tractor  │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ HITCH POINT                 │        │             │                      │
  │ TowHitchOffset              │ vec3   │ 0,-0.3,-2   │ Fallback if no node  │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ INPUT                       │        │             │                      │
  │ TowHitchKey                 │KeyCode │ H           │                      │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ MOD REQUIREMENT             │        │             │                      │
  │ TowHitchMod                 │ string │ ""          │ Empty = always on    │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ SEARCH & APPROACH           │        │             │                      │
  │ TowHitchSearchRadius        │ float  │ 5.0         │ meters               │
  │ TowHitchApproachSpeed       │ float  │ 3.0         │ m/s                  │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ JOINT PHYSICS               │        │             │                      │
  │ TowHitchSpring              │ float  │ 2000        │                      │
  │ TowHitchDamper              │ float  │ 200         │                      │
  │ TowHitchMaxForce            │ float  │ 4000        │                      │
  │ TowHitchMaxAngle            │ float  │ 45          │ degrees yaw/pitch    │
  │ TowHitchRollLimit           │ float  │ 15          │ degrees roll, 0=free │
  │ TowHitchSwayDamping         │ float  │ 0.08        │ 0=free, 0.15=stiff   │
  │ TowHitchWheelFriction       │ float  │ 0.6         │ 0=slip, 1=grip       │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ ROPE / CABLE                │        │             │                      │
  │ TowHitchRope                │ bool   │ false       │ Enables rope system  │
  │ TowHitchRopeSegments        │ int    │ 16          │                      │
  │ TowHitchRopeSag             │ float  │ 1.2         │                      │
  │ TowHitchRopeDeployLength    │ float  │ 4.0         │ meters               │
  │ TowHitchRopeDescendSpeed    │ float  │ 2.0         │ m/s                  │
  │ TowHitchRopeWidth           │ float  │ 0.03        │ meters               │
  │ TowHitchRopeSwing           │ float  │ 0.2         │                      │
  │ TowHitchRopeColor           │ R,G,B  │ .15,.15,.15 │                      │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ MAGNET (rope tip)           │        │             │                      │
  │ TowHitchMagnetSize          │ float  │ 0.25        │ 0 = hidden           │
  │ TowHitchMagnetWeight        │ float  │ 20          │ visual scale only    │
  │ TowHitchMagnetRopeT         │ float  │ 1.0         │ 0=origin, 1=tip      │
  │ TowHitchMagnetRotation      │ vec3   │ 0,0,0       │ euler degrees        │
  │ TowHitchMagnetName          │ string │ TowMagnet   │ prefab node name     │
  │ TowHitchMagnetColor         │ R,G,B  │ .3,.3,.35   │                      │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ AERIAL TOW                  │        │             │                      │
  │ TowHitchAerial              │ bool   │ false       │ Needs TowHitchRope   │
  │ TowHitchAerialAngle         │ float  │ 60          │ degrees              │
  └─────────────────────────────┴────────┴─────────────┴──────────────────────┘

  TRAILER PROPERTIES
  ┌─────────────────────────────┬────────┬─────────────┬──────────────────────┐
  │ Property                    │ Type   │ Default     │ Notes                │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ Towable                     │ bool   │ —           │ REQUIRED on trailer  │
  │ TowableHitchOffset          │ vec3   │ 0,0.3,1.8   │ Fallback if no node  │
  │ TowableMassScale            │ float  │ 0.15        │ 0.05–0.30            │
  └─────────────────────────────┴────────┴─────────────┴──────────────────────┘

  ═══════════════════════════════════════════════════════════════════════════════
  QUICK REFERENCE TABLE — VehicleCarrier
  ═══════════════════════════════════════════════════════════════════════════════

  No XML properties needed on the carrier or cargo vehicles.
  Configuration is done entirely in Unity:

  ┌─────────────────────────────┬──────────────────────────────────────────────┐
  │ Unity Setup                 │ Description                                  │
  ├─────────────────────────────┼──────────────────────────────────────────────┤
  │ BoxCollider named "Carrier" │ REQUIRED on carrier vehicle. Defines the     │
  │                             │ snap/carry zone. Must be enabled. Can be     │
  │                             │ placed under any node in the hierarchy.      │
  │ TowHitch empty object       │ OPTIONAL on tractor. Exact hitch position.   │
  │ TowableHitch empty object   │ OPTIONAL on trailer. Exact coupling position.│
  │ TowMagnet empty/mesh object │ OPTIONAL. Custom magnet visual on rope tip.  │
  └─────────────────────────────┴──────────────────────────────────────────────┘

  ═══════════════════════════════════════════════════════════════════════════════
  NOTES & TIPS
  ═══════════════════════════════════════════════════════════════════════════════

  TOWING SYSTEM:
  ● TowHitch and Towable are the only required properties. Everything else
	has sensible defaults.
  ● Named empty objects (TowHitch, TowableHitch) take priority over XML offsets.
	Use them for precision — XML offsets are just fallbacks.
  ● TowHitchMod: if set, the named mod must be installed on the tractor.
	If missing, the hitch key shows a notification and does nothing.
  ● TowHitchRollLimit=0 removes the roll limit entirely (free lateral tilt).
  ● The rope system (TowHitchRope=true) adds a two-press workflow:
	  Press 1 → deploys rope downward.
	  Press 2 → attaches when rope tip is near a Towable vehicle.
	  Press 3 → detaches and retracts rope.
  ● TowHitchAerial=true requires TowHitchRope=true. It makes the trailer
	hang below the tractor using rope length as vertical distance. Ideal
	for helicopters lifting vehicles.
  ● TowHitchAerialAngle controls pendulum freedom. 60° is generous;
	reduce to 30° for a tighter, more controlled lift.
  ● The magnet visual (TowHitchMagnetName) can reference any child
	GameObject in the prefab. If found, it replaces the default sphere.
  ● TowHitchRopeColor uses R,G,B (0.0–1.0). No alpha channel.
  ● The tow key row appears automatically in the VehicleKeybindOverlay
	UI panel when TowHitch=true is set, allowing players to rebind H
	without touching any XML.
  ● A vehicle cannot be both a tractor (TowHitch=true) and a trailer
	(Towable=true) simultaneously in the same link — but the same vehicle
	class can have both properties to support different use cases.

  CARRIER SYSTEM:
  ● No XML is needed. Everything is controlled by the "Carrier" BoxCollider.
  ● Size the BoxCollider to match the actual platform surface. Too large and
	nearby vehicles will snap unexpectedly; too small and alignment is hard.
  ● Cargo is automatically locked when a player exits a vehicle that is
	inside the zone, and released when a player enters and drives it out.
  ● Multiple cargo vehicles can be carried simultaneously (one carrier,
	many cargos).
  ● The carrier system is fully multiplayer-safe with server authority,
	sequence numbers and automatic state sync for late-joining clients.
  ● If cargo is destroyed while carried, it is released cleanly.
  ● Carrier and tow systems can coexist: a helicopter can carry a flatbed
	(VehicleCarrier) while the flatbed tows a trailer (VehicleTowSystem).
  -->

</transport_reference>
