<?xml version="1.0" encoding="utf-8"?>
<!--
  ═══════════════════════════════════════════════════════════════════════════════
  WitosRoot — Sistemas de Transporte de Vehículos  [ESPAÑOL]
  VehicleTowSystem  +  VehicleCarrier
  ═══════════════════════════════════════════════════════════════════════════════

  Este archivo documenta dos sistemas de transporte independientes que pueden
  coexistir en el mismo vehículo o usarse por separado:

	1. VehicleTowSystem  — sistema de remolque con física de articulación
	2. VehicleCarrier    — sistema de transporte rígido (plataforma, helipuerto)

  ═══════════════════════════════════════════════════════════════════════════════
-->

<transport_reference>

<!-- ═══════════════════════════════════════════════════════════════════════════
	 PARTE 1 — VehicleTowSystem
	 Remolque por física con ConfigurableJoint, cuerda, imán, modo aéreo
	 ═══════════════════════════════════════════════════════════════════════════

	 CÓMO FUNCIONA
	 ─────────────
	 Pulsa la tecla de enganche (por defecto H) mientras conduces para
	 activar o desactivar el enganche. El sistema busca el vehículo remolcable
	 más cercano (Towable=true) dentro del radio de búsqueda. Si lo encuentra,
	 el remolque se aproxima al punto de enganche y se conecta con un
	 ConfigurableJoint de Unity, lo que genera inercia real, balanceo y
	 fricción de ruedas auténtica.

	 Si se activa TowHitchRope=true, al pulsar H se despliega primero una
	 cuerda/cable. Un segundo toque cuando la punta está cerca del remolque
	 lo engancha. Un tercer toque lo suelta y recoge la cuerda.

	 UNITY — OBJETOS VACÍOS EN EL PREFAB
	 ─────────────────────────────────────
	 En lugar de offsets XML puedes colocar GameObjects vacíos en el prefab
	 con estos nombres exactos. El sistema busca en toda la jerarquía.
	 Si no se encuentran, usa los valores XML como respaldo.

	   Tractor  →  TowHitch        (vacío en la bola de enganche trasera)
	   Remolque →  TowableHitch    (vacío en el gancho delantero)
	   Imán     →  TowMagnet       (opcional, punta de la cuerda)

	 ═══════════════════════════════════════════════════════════════════════════
	 VEHÍCULO TRACTOR  (el que remolca)
	 ═══════════════════════════════════════════════════════════════════════════ -->

  <vehicle name="miTractor_ejemplo">

	<!-- ── OBLIGATORIO ───────────────────────────────────────────────────── -->

	<!-- Activa el sistema de enganche en este vehículo. OBLIGATORIO. -->
	<property name="TowHitch"               value="true"/>

	<!-- ── PUNTO DE ENGANCHE ─────────────────────────────────────────────── -->

	<!-- Offset local del punto de enganche respecto al centro Physics.
		 Solo se usa si no existe un objeto vacío llamado TowHitch en el prefab.
		 Formato: X, Y, Z  (metros, espacio local del Physics transform)
		 X=0 centrado | Y negativo = hacia abajo | Z negativo = hacia atrás -->
	<property name="TowHitchOffset"         value="0,-0.3,-2.5"/>

	<!-- ── ENTRADA ───────────────────────────────────────────────────────── -->

	<!-- Tecla para enganchar/desenganchar. Cualquier nombre Unity KeyCode.
		 Ejemplos: H, G, T, F, JoystickButton0
		 Valor por defecto: H -->
	<property name="TowHitchKey"            value="H"/>

	<!-- ── REQUISITO DE MOD ──────────────────────────────────────────────── -->

	<!-- Nombre de un mod de vehículo que debe estar instalado para que el
		 enganche funcione. Si está vacío o se omite, el enganche siempre
		 está disponible. Si el mod falta, se muestra una notificación. -->
	<property name="TowHitchMod"            value="modTowHitch"/>

	<!-- ── BÚSQUEDA Y APROXIMACIÓN ───────────────────────────────────────── -->

	<!-- Radio de búsqueda en metros desde el punto TowHitch.
		 El remolque debe estar dentro de esta distancia para engancharse.
		 Valor por defecto: 5.0 -->
	<property name="TowHitchSearchRadius"   value="4.5"/>

	<!-- Velocidad (m/s) a la que el remolque se desliza hacia el enganche
		 antes de crear la articulación. Menor = más lento y cinemático.
		 Valor por defecto: 3.0 -->
	<property name="TowHitchApproachSpeed"  value="3.0"/>

	<!-- ── FÍSICA DE LA ARTICULACIÓN ─────────────────────────────────────── -->

	<!-- Rigidez del muelle (spring). Mayor = conexión más rígida, menos
		 retraso del remolque. Menor = más flotante.
		 Valor por defecto: 2000 -->
	<property name="TowHitchSpring"         value="2000"/>

	<!-- Amortiguación de la articulación. Reduce las oscilaciones.
		 Aumentar si el remolque vibra en exceso.
		 Valor por defecto: 200 -->
	<property name="TowHitchDamper"         value="200"/>

	<!-- Fuerza máxima que puede aplicar la articulación.
		 Limita cuánto puede tirar el remolque del tractor en pendientes.
		 Valor por defecto: 4000 -->
	<property name="TowHitchMaxForce"       value="4000"/>

	<!-- Límite angular máximo del enganche en grados (guiñada/cabeceo).
		 45° permite giros cerrados. 30° es más rígido.
		 Valor por defecto: 45 -->
	<property name="TowHitchMaxAngle"       value="45"/>

	<!-- Límite máximo de alabeo (inclinación lateral) en grados.
		 Controla cuánto puede inclinarse el remolque al pasar por baches.
		 5–10 = muy rígido | 15 = comportamiento realista | 25–40 = muy suelto.
		 0 = libre (sin límite de alabeo).
		 Valor por defecto: 15 -->
	<property name="TowHitchRollLimit"      value="15"/>

	<!-- Amortiguación del balanceo lateral del remolque cada fotograma.
		 0.0  = balanceo libre infinito.
		 0.08 = amortiguación suave realista.
		 0.15 = muy estable, casi sin balanceo.
		 Valor por defecto: 0.08 -->
	<property name="TowHitchSwayDamping"    value="0.08"/>

	<!-- Rigidez lateral de las ruedas del remolque mientras está enganchado.
		 1.0 = agarre completo (sigue la trayectoria exacta del tractor).
		 0.6 = algo de deslizamiento lateral realista.
		 0.3 = ruedas muy resbaladizas.
		 Valor por defecto: 0.6 -->
	<property name="TowHitchWheelFriction"  value="0.6"/>

	<!-- ── SISTEMA DE CUERDA / CABLE ─────────────────────────────────────── -->

	<!-- Activa el sistema de cuerda/cable desplegable.
		 Con true, pulsar H despliega la cuerda primero. Un segundo toque
		 cuando la punta está cerca de un remolque lo engancha. Un tercer
		 toque lo desconecta.
		 Valor por defecto: false (enganche directo sin cuerda) -->
	<property name="TowHitchRope"            value="true"/>

	<!-- Número de segmentos en la simulación catenaria de la cuerda.
		 Más segmentos = curva más suave pero algo más de CPU.
		 Valor por defecto: 16 -->
	<property name="TowHitchRopeSegments"    value="16"/>

	<!-- Factor de curvatura de la cuerda. Mayor = más caída en el centro.
		 Valor por defecto: 1.2 -->
	<property name="TowHitchRopeSag"         value="1.2"/>

	<!-- Longitud máxima que despliega la cuerda (metros).
		 También es la distancia vertical en el modo de remolque aéreo.
		 Valor por defecto: 4.0 -->
	<property name="TowHitchRopeDeployLength" value="4.0"/>

	<!-- Velocidad a la que baja la punta de la cuerda al desplegar (m/s).
		 Valor por defecto: 2.0 -->
	<property name="TowHitchRopeDescendSpeed" value="2.0"/>

	<!-- Grosor visual de la línea de la cuerda (metros).
		 Valor por defecto: 0.03 -->
	<property name="TowHitchRopeWidth"        value="0.03"/>

	<!-- Amplitud del balanceo lateral de la punta durante el despliegue.
		 0 = sin balanceo | 0.2 = suave efecto péndulo.
		 Valor por defecto: 0.2 -->
	<property name="TowHitchRopeSwing"        value="0.2"/>

	<!-- Color de la línea de la cuerda (R,G,B — cada valor de 0.0 a 1.0).
		 Valor por defecto: 0.15,0.15,0.15 (gris oscuro) -->
	<property name="TowHitchRopeColor"        value="0.15,0.15,0.15"/>

	<!-- ── IMÁN (punta de la cuerda) ─────────────────────────────────────── -->

	<!-- Tamaño visual de la esfera del imán en la punta (metros).
		 0 = imán oculto.
		 Valor por defecto: 0.25 -->
	<property name="TowHitchMagnetSize"       value="0.25"/>

	<!-- Escala visual del imán (solo afecta proporciones, no física).
		 Valor por defecto: 20 -->
	<property name="TowHitchMagnetWeight"     value="20"/>

	<!-- Posición a lo largo de la cuerda donde se coloca el imán.
		 0.0 = origen del enganche | 1.0 = punta.
		 Mantener en 1.0 para que esté en la punta.
		 Valor por defecto: 1.0 -->
	<property name="TowHitchMagnetRopeT"      value="1.0"/>

	<!-- Rotación Euler del imán visual (X,Y,Z en grados).
		 Útil si la malla del imán apunta en la dirección incorrecta.
		 Valor por defecto: 0,0,0 -->
	<property name="TowHitchMagnetRotation"   value="0,0,0"/>

	<!-- Nombre del hijo del prefab a usar como visual del imán.
		 Si se encuentra, reemplaza la esfera procedural.
		 Valor por defecto: TowMagnet -->
	<property name="TowHitchMagnetName"       value="TowMagnet"/>

	<!-- Color de la esfera procedural del imán (R,G,B).
		 Valor por defecto: 0.3,0.3,0.35 (azul-gris oscuro) -->
	<property name="TowHitchMagnetColor"      value="0.3,0.3,0.35"/>

	<!-- ── REMOLQUE AÉREO (modo helicóptero) ──────────────────────────────── -->

	<!-- Activa el modo de remolque aéreo. Con true el remolque cuelga por
		 debajo del tractor (p. ej. helicóptero levantando un vehículo) en
		 lugar de ser empujado por el suelo.
		 Requiere TowHitchRope=true.
		 Valor por defecto: false -->
	<property name="TowHitchAerial"           value="false"/>

	<!-- Ángulo máximo de oscilación (grados) del remolque colgante en
		 modo aéreo. Mayor = más libertad de péndulo.
		 Valor por defecto: 60 -->
	<property name="TowHitchAerialAngle"      value="60"/>

  </vehicle>

<!-- ═══════════════════════════════════════════════════════════════════════════
	 VEHÍCULO REMOLQUE  (el que es remolcado)
	 ═══════════════════════════════════════════════════════════════════════════ -->

  <vehicle name="miRemolque_ejemplo">

	<!-- Marca este vehículo como remolcable.
		 Sin esta propiedad el sistema lo ignorará aunque esté cerca. OBLIGATORIO. -->
	<property name="Towable"                value="true"/>

	<!-- Offset local del punto de acoplamiento en el remolque.
		 Solo se usa si no existe un objeto vacío llamado TowableHitch en el prefab.
		 Formato: X, Y, Z  (metros, espacio local del Physics transform)
		 X=0 centrado | Y positivo = hacia arriba | Z positivo = hacia delante -->
	<property name="TowableHitchOffset"     value="0,0.3,1.8"/>

	<!-- Escala de masa aplicada al Rigidbody del remolque mientras está enganchado.
		 Reduce temporalmente la masa efectiva para que el tractor no sienta
		 el peso completo durante la conducción.
		 0.05 = casi sin peso | 0.15 = ligero | 0.30 = todavía bastante pesado.
		 La masa original se restaura automáticamente al desenganchar.
		 Valor por defecto: 0.15 -->
	<property name="TowableMassScale"       value="0.15"/>

  </vehicle>


<!-- ═══════════════════════════════════════════════════════════════════════════
	 PARTE 2 — VehicleCarrier
	 Sistema de transporte rígido: camiones plataforma, helipuertos, portadores
	 ═══════════════════════════════════════════════════════════════════════════

	 CÓMO FUNCIONA
	 ─────────────
	 El vehículo portador tiene una zona trigger definida por un BoxCollider
	 llamado exactamente "Carrier" en el prefab de Unity. Cuando un jugador
	 sale de un vehículo que está dentro de esa zona (o el vehículo
	 aterriza/aparece sobre la plataforma), el sistema congela automáticamente
	 la carga y la bloquea al portador.
	 No se necesitan propiedades XML en el portador — solo el BoxCollider de Unity.

	 La carga se libera automáticamente cuando un jugador entra y la conduce
	 fuera, o cuando el portador es destruido.

	 UNITY — ZONA DEL PORTADOR
	 ──────────────────────────
	 Añade un BoxCollider a cualquier hijo del vehículo portador y nómbralo
	 exactamente "Carrier". Este colisionador define la zona de enganche:

	   RaízPortador
	   └── Carrier        ← BoxCollider (habilitado; isTrigger no es obligatorio)
							 Dimensiónalo para cubrir el área de la plataforma.

	 El sistema busca en toda la jerarquía, así que puede estar bajo cualquier
	 nodo padre (Physics, M, GameObject, etc.).

	 COMPORTAMIENTO DE LA CARGA MIENTRAS SE TRANSPORTA
	 ───────────────────────────────────────────────────
	 Mientras un vehículo es transportado:
	 - Su Rigidbody queda congelado (cinemático, sin gravedad, sin colisión).
	 - Sus ruedas y colisionadores se deshabilitan.
	 - Su motor se apaga.
	 - Se mueve y rota rígidamente con el portador cada fotograma.
	 - Todo se restaura automáticamente al ser liberado.

	 MULTIJUGADOR
	 ─────────────
	 El sistema es completamente autoritativo del servidor. El servidor asigna
	 la carga, difunde el estado a todos los clientes y gestiona jugadores que
	 se unen tarde mediante una solicitud de sincronización de estado.
	 Los números de secuencia evitan actualizaciones desordenadas.

	 VEHÍCULO CARGA — SIN XML REQUERIDO
	 ─────────────────────────────────────
	 Cualquier vehículo que esté físicamente dentro de la zona BoxCollider
	 "Carrier" cuando un jugador lo abandone será recogido automáticamente.
	 No se necesita configuración XML en el vehículo carga. -->


<!-- ═══════════════════════════════════════════════════════════════════════════
	 TABLA DE REFERENCIA RÁPIDA — VehicleTowSystem
	 ═══════════════════════════════════════════════════════════════════════════

  PROPIEDADES DEL TRACTOR
  ┌─────────────────────────────┬────────┬─────────────┬──────────────────────┐
  │ Propiedad                   │ Tipo   │ Por defecto │ Notas                │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ OBLIGATORIO                 │        │             │                      │
  │ TowHitch                    │ bool   │ —           │ OBLIGATORIO          │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ PUNTO DE ENGANCHE           │        │             │                      │
  │ TowHitchOffset              │ vec3   │ 0,-0.3,-2   │ Respaldo sin nodo    │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ ENTRADA                     │        │             │                      │
  │ TowHitchKey                 │KeyCode │ H           │                      │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ REQUISITO DE MOD            │        │             │                      │
  │ TowHitchMod                 │ string │ ""          │ Vacío = siempre activo│
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ BÚSQUEDA Y APROXIMACIÓN     │        │             │                      │
  │ TowHitchSearchRadius        │ float  │ 5.0         │ metros               │
  │ TowHitchApproachSpeed       │ float  │ 3.0         │ m/s                  │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ FÍSICA DE LA ARTICULACIÓN   │        │             │                      │
  │ TowHitchSpring              │ float  │ 2000        │                      │
  │ TowHitchDamper              │ float  │ 200         │                      │
  │ TowHitchMaxForce            │ float  │ 4000        │                      │
  │ TowHitchMaxAngle            │ float  │ 45          │ grados guiñ./cabeceo │
  │ TowHitchRollLimit           │ float  │ 15          │ grados alabeo, 0=libre│
  │ TowHitchSwayDamping         │ float  │ 0.08        │ 0=libre, 0.15=rígido │
  │ TowHitchWheelFriction       │ float  │ 0.6         │ 0=desliz., 1=agarre  │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ CUERDA / CABLE              │        │             │                      │
  │ TowHitchRope                │ bool   │ false       │ Activa sistema cuerda│
  │ TowHitchRopeSegments        │ int    │ 16          │                      │
  │ TowHitchRopeSag             │ float  │ 1.2         │                      │
  │ TowHitchRopeDeployLength    │ float  │ 4.0         │ metros               │
  │ TowHitchRopeDescendSpeed    │ float  │ 2.0         │ m/s                  │
  │ TowHitchRopeWidth           │ float  │ 0.03        │ metros               │
  │ TowHitchRopeSwing           │ float  │ 0.2         │                      │
  │ TowHitchRopeColor           │ R,G,B  │ .15,.15,.15 │                      │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ IMÁN (punta cuerda)         │        │             │                      │
  │ TowHitchMagnetSize          │ float  │ 0.25        │ 0 = oculto           │
  │ TowHitchMagnetWeight        │ float  │ 20          │ solo escala visual    │
  │ TowHitchMagnetRopeT         │ float  │ 1.0         │ 0=origen, 1=punta    │
  │ TowHitchMagnetRotation      │ vec3   │ 0,0,0       │ grados Euler         │
  │ TowHitchMagnetName          │ string │ TowMagnet   │ nombre nodo prefab   │
  │ TowHitchMagnetColor         │ R,G,B  │ .3,.3,.35   │                      │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ REMOLQUE AÉREO              │        │             │                      │
  │ TowHitchAerial              │ bool   │ false       │ Necesita TowHitchRope│
  │ TowHitchAerialAngle         │ float  │ 60          │ grados               │
  └─────────────────────────────┴────────┴─────────────┴──────────────────────┘

  PROPIEDADES DEL REMOLQUE
  ┌─────────────────────────────┬────────┬─────────────┬──────────────────────┐
  │ Propiedad                   │ Tipo   │ Por defecto │ Notas                │
  ├─────────────────────────────┼────────┼─────────────┼──────────────────────┤
  │ Towable                     │ bool   │ —           │ OBLIGATORIO          │
  │ TowableHitchOffset          │ vec3   │ 0,0.3,1.8   │ Respaldo sin nodo    │
  │ TowableMassScale            │ float  │ 0.15        │ 0.05–0.30            │
  └─────────────────────────────┴────────┴─────────────┴──────────────────────┘

  ═══════════════════════════════════════════════════════════════════════════════
  TABLA DE REFERENCIA RÁPIDA — VehicleCarrier
  ═══════════════════════════════════════════════════════════════════════════════

  No se necesitan propiedades XML. La configuración es íntegramente en Unity:

  ┌─────────────────────────────┬──────────────────────────────────────────────┐
  │ Configuración Unity         │ Descripción                                  │
  ├─────────────────────────────┼──────────────────────────────────────────────┤
  │ BoxCollider llamado Carrier │ OBLIGATORIO en el portador. Define la zona   │
  │                             │ de enganche. Debe estar habilitado. Puede    │
  │                             │ colocarse bajo cualquier nodo de la jerarquía│
  │ Objeto vacío TowHitch       │ OPCIONAL en el tractor. Posición exacta      │
  │                             │ del enganche.                                │
  │ Objeto vacío TowableHitch   │ OPCIONAL en el remolque. Posición exacta del │
  │                             │ punto de acoplamiento.                       │
  │ Objeto/malla TowMagnet      │ OPCIONAL. Visual personalizado del imán.     │
  └─────────────────────────────┴──────────────────────────────────────────────┘

  ═══════════════════════════════════════════════════════════════════════════════
  NOTAS Y CONSEJOS
  ═══════════════════════════════════════════════════════════════════════════════

  SISTEMA DE REMOLQUE:
  ● TowHitch y Towable son las únicas propiedades obligatorias. El resto
	tiene valores por defecto razonables.
  ● Los objetos vacíos con nombre (TowHitch, TowableHitch) tienen prioridad
	sobre los offsets XML. Úsalos para mayor precisión.
  ● TowHitchMod: si se define, ese mod debe estar instalado en el tractor.
	Si falta, la tecla de enganche muestra una notificación y no hace nada.
  ● TowHitchRollLimit=0 elimina por completo el límite de alabeo (inclinación
	lateral libre).
  ● El sistema de cuerda (TowHitchRope=true) añade un flujo de dos pulsaciones:
	  Pulsación 1 → despliega la cuerda hacia abajo.
	  Pulsación 2 → engancha cuando la punta está cerca de un vehículo Towable.
	  Pulsación 3 → desconecta y recoge la cuerda.
  ● TowHitchAerial=true requiere TowHitchRope=true. Hace que el remolque
	cuelgue debajo del tractor usando la longitud de la cuerda como distancia
	vertical. Ideal para helicópteros que levantan vehículos.
  ● TowHitchAerialAngle controla la libertad de péndulo. 60° es generoso;
	reduce a 30° para un izado más controlado.
  ● El visual del imán (TowHitchMagnetName) puede referenciar cualquier hijo
	del prefab. Si se encuentra, reemplaza la esfera por defecto.
  ● TowHitchRopeColor usa R,G,B (0.0–1.0). Sin canal alfa.
  ● La fila de la tecla de remolque aparece automáticamente en el panel de
	teclas del vehículo (VehicleKeybindOverlay) cuando TowHitch=true está
	configurado, permitiendo a los jugadores reasignar H sin tocar XML.
  ● Un vehículo no puede ser tractor (TowHitch=true) y remolque (Towable=true)
	en el mismo enlace al mismo tiempo — pero la misma clase de vehículo
	puede tener ambas propiedades para casos de uso distintos.

  SISTEMA DE TRANSPORTE (CARRIER):
  ● No se necesita XML. Todo está controlado por el BoxCollider "Carrier".
  ● Dimensiona el BoxCollider para que coincida con la superficie real de la
	plataforma. Demasiado grande y vehículos cercanos se engancharán de forma
	inesperada; demasiado pequeño y el alineamiento será difícil.
  ● La carga se bloquea automáticamente cuando un jugador abandona un vehículo
	que está dentro de la zona, y se libera cuando un jugador entra y lo saca.
  ● Se pueden transportar varios vehículos carga simultáneamente (un portador,
	muchas cargas).
  ● El sistema de portador es completamente seguro en multijugador con
	autoridad del servidor, números de secuencia y sincronización automática
	para clientes que se unen tarde.
  ● Si la carga es destruida mientras se transporta, se libera limpiamente.
  ● Los sistemas de portador y remolque pueden coexistir: un helicóptero puede
	transportar una plataforma (VehicleCarrier) mientras la plataforma remolca
	un tráiler (VehicleTowSystem).
  -->

</transport_reference>
