vehiclelayouts.meta explicado: asientos, puntos de entrada y animaciones

Un layout es una lista con nombre de asientos y puntos de entrada. Cada asiento empareja una definición de asiento (qué bone, qué vecinos) con una definición de animación de asiento (qué clips se reproducen en él). Cada punto de entrada empareja una definición de puerta con una definición de animación de entrada. Todo se referencia por nombre, así que un layout puede reutilizar piezas de los layouts originales.

Este es el LAYOUT_STANDARD original, el que usan los coches por defecto, reducido a sus dos asientos delanteros:

<Item type="CVehicleLayoutInfo">
  <Name>LAYOUT_STANDARD</Name>
  <Seats>
    <Item>
      <SeatInfo ref="SEAT_STANDARD_FRONT_LEFT" />
      <SeatAnimInfo ref="SEAT_ANIM_STANDARD_FRONT_LEFT" />
    </Item>
    <Item>
      <SeatInfo ref="SEAT_STANDARD_FRONT_RIGHT" />
      <SeatAnimInfo ref="SEAT_ANIM_STANDARD_FRONT_RIGHT" />
    </Item>
  </Seats>
  <EntryPoints>
    <Item>
      <EntryPointInfo ref="ENTRY_POINT_STANDARD_FRONT_LEFT" />
      <EntryPointAnimInfo ref="ENTRY_POINT_ANIM_STANDARD_FRONT_LEFT" />
    </Item>
    <Item>
      <EntryPointInfo ref="ENTRY_POINT_STANDARD_FRONT_RIGHT" />
      <EntryPointAnimInfo ref="ENTRY_POINT_ANIM_STANDARD_FRONT_RIGHT" />
    </Item>
  </EntryPoints>
  <LayoutFlags>StreamAnims UseDoorOscillation UseLeanSteerAnims UseSteeringWheelIk</LayoutFlags>
  <BicycleInfo ref="NULL" />
  <AnimRateSet ref="STD_LOW_ANIM_RATE_SET" />
  <HandsUpClipSetId>busted_vehicle_std</HandsUpClipSetId>
  <SteeringWheelOffset x="0.000000" y="0.350000" z="0.320000" />
</Item>

El elemento raíz es CVehicleMetadataMgr. Contiene una lista por cada tipo de definición. Un archivo solo necesita las listas a las que añade algo. Los nombres que referencia pero no define se toman de los archivos del propio juego.

Lista	Tipo de elemento	Qué define
VehicleLayoutInfos	CVehicleLayoutInfo	El layout: asientos, puntos de entrada, flags.
VehicleSeatInfos	CVehicleSeatInfo	Un asiento: bone, enlaces para cambiar de asiento, flags del asiento.
VehicleSeatAnimInfos	CVehicleSeatAnimInfo	Animaciones que se usan estando en un asiento, configuración de drive-by.
VehicleEntryPointInfos	CVehicleEntryPointInfo	Una forma de entrar: bone de la puerta, lado, a qué asientos da acceso.
VehicleEntryPointAnimInfos	CVehicleEntryPointAnimInfo	Animaciones para subir y bajar por un punto de entrada.
ClipSetMaps	CClipSetMap	Listas con nombre de clip sets a las que apuntan los anim infos.
VehicleDriveByInfos, VehicleDriveByAnimInfos		Apuntar y disparar desde un asiento.
AnimRateSets, BicycleInfos, VehicleExtraPointsInfos, EntryAnimVariations, VehicleCoverBoundOffsetInfos, VehicleExplosionInfos		Velocidades de animación, pedaleo de bicicletas, posiciones de entrada extra, variaciones de entrada, configuraciones de cobertura y de explosión.

Campo	Significado
Name	El nombre del layout que se usa en el campo layout de vehicles.meta.
Seats	Un elemento por asiento, cada uno con una referencia a un SeatInfo y a un SeatAnimInfo.
EntryPoints	Un elemento por cada forma de entrar, cada uno con una referencia a un EntryPointInfo y a un EntryPointAnimInfo.
LayoutFlags	Flags de comportamiento separados por espacios (ver abajo).
BicycleInfo	Configuración de pedaleo para bicicletas; si no, NULL.
AnimRateSet	Conjunto de velocidades de animación para entrar y salir.
HandsUpClipSetId	Clip set de la postura de manos arriba (por defecto busted_vehicle_std).
SteeringWheelOffset	Posición del volante que se usa para colocar las manos (por defecto 0, 0.35, 0.32).
FirstPersonAdditiveIdleClipSets, FirstPersonRoadRageClipSets	Clip sets de reposo y de furia al volante en primera persona.

Algunos de los flags de layout, con lo que dicen sus nombres: NoDriver, StreamAnims, WarpIntoAndOut, BikeLeansUnlessMoving, UseSteeringWheelIk, UseLeanSteerAnims, MustCloseDoor, AutomaticCloseDoor, DisableJackingAndBusting, UseDoorOscillation, WarpInWhenStoodOnTop. El esquema define 32 en total. Parte de los flags del layout original más parecido a tu vehículo y cambia uno cada vez.

Un asiento está ligado a un bone del modelo del vehículo, y un punto de entrada a un bone de puerta. Si el modelo no tiene el bone que nombra la definición, ese asiento o esa puerta no pueden funcionar. Estos son el asiento del conductor y la puerta del conductor originales de un coche:

<Item type="CVehicleSeatInfo">
  <Name>SEAT_STANDARD_FRONT_LEFT</Name>
  <SeatBoneName>seat_dside_f</SeatBoneName>
  <ShuffleLink>SEAT_STANDARD_FRONT_RIGHT</ShuffleLink>
  <RearSeatLink>SEAT_STANDARD_REAR_LEFT</RearSeatLink>
  <DefaultCarTask>TASK_DRIVE_WANDER</DefaultCarTask>
  <SeatFlags>IsFrontSeat</SeatFlags>
  <HairScale value="-0.2750000" />
</Item>

<Item type="CVehicleEntryPointInfo">
  <Name>ENTRY_POINT_STANDARD_FRONT_LEFT</Name>
  <DoorBoneName>door_dside_f</DoorBoneName>
  <SecondDoorBoneName />
  <DoorHandleBoneName>handle_dside_f</DoorHandleBoneName>
  <WindowId>FRONT_LEFT</WindowId>
  <VehicleSide>SIDE_LEFT</VehicleSide>
  <AccessableSeats>
    <Item ref="SEAT_STANDARD_FRONT_LEFT" />
  </AccessableSeats>
  <VehicleExtraPointsInfo ref="EXTRA_VEHICLE_POINTS_STD_LEFT" />
  <Flags>BlockJackReactionUntilJackerIsReady</Flags>
  <BlockJackReactionSides>
    <Item>SIDE_LEFT</Item>
  </BlockJackReactionSides>
</Item>

Campo	Significado
SeatBoneName	Bone al que se engancha el ped. Los coches usan seat_dside_f, seat_pside_f, seat_dside_r y seat_pside_r (lado del conductor y lado del pasajero, delante y detrás).
ShuffleLink	Asiento al que se desliza un ped, por ejemplo del pasajero al conductor.
RearSeatLink	El asiento que está detrás de este.
SeatFlags	Por ejemplo IsFrontSeat, IsIdleSeat, NoIndirectExit, KeepOnHeadProp, FakeSeat.
DoorBoneName, DoorHandleBoneName	Bones de la puerta y de la manilla hacia los que camina el ped y a los que alarga la mano, por ejemplo door_dside_f y handle_dside_f. Se dejan vacíos en los vehículos sin puertas.
WindowId	FRONT_LEFT, FRONT_RIGHT, REAR_LEFT, REAR_RIGHT, MID_LEFT, MID_RIGHT, FRONT_WINDSCREEN, REAR_WINDSCREEN o INVALID.
VehicleSide	SIDE_LEFT, SIDE_RIGHT o SIDE_REAR.
AccessableSeats	Asientos a los que se puede llegar desde este punto de entrada. La grafía con a es el nombre real de la etiqueta.

Las animaciones llegan a un asiento pasando por cuatro enlaces. Cada enlace es una búsqueda por nombre, así que si la cadena se rompe en cualquier punto te quedas con la animación original o con ninguna.

1. El archivo de animación, un diccionario de clips (.ycd), va en la carpeta stream del resource.
2. Un clip set en clip_sets.xml le da a ese diccionario un nombre de clip set. Se carga con data_file 'CLIP_SETS_FILE'.
3. Un CClipSetMap en vehiclelayouts.meta incluye ese nombre de clip set en ClipSetId.
4. Un anim info de asiento apunta al mapa con InsideClipSetMap (clips que se reproducen estando sentado), y un anim info de punto de entrada con EntryClipSetMap, ExitClipSetMap y CommonClipSetMap.

<?xml version="1.0" encoding="UTF-8"?>
<fwClipSetManager>
  <clipSets>
    <Item type="fwClipSet" key="veh@bike@mybike@front@base">
      <fallbackId />
      <clipDictionaryName>veh@bike@mybike@front@base</clipDictionaryName>
      <clipItems />
      <moveNetworkFlags />
    </Item>
  </clipSets>
  <clipDictionaryMetadatas>
    <Item key="veh@bike@mybike@front@base">
      <streamingPolicy>SP_STREAMING</streamingPolicy>
      <memoryGroup>MG_Vehicle</memoryGroup>
      <streamingPriority>SP_Medium</streamingPriority>
    </Item>
  </clipDictionaryMetadatas>
</fwClipSetManager>

El juego le pide los clips a un clip set por nombres fijos, así que un diccionario personalizado conserva los nombres de clip del diccionario original al que sustituye y solo cambia el movimiento que llevan dentro.

Crea un layout con un nombre nuevo, copia el layout original que el vehículo usaría normalmente y reemplaza solo las referencias que quieras cambiar. Todo lo que no redefinas sigue apuntando a las definiciones originales.

<CVehicleMetadataMgr>
  <ClipSetMaps>
    <Item type="CClipSetMap">
      <Name>INSIDE_CLIPSET_MAP_MYBIKE_FRONT</Name>
      <Maps>
        <Item>
          <ClipSetId>veh@bike@mybike@front@base</ClipSetId>
          <VarClipSetId>InsideVarClipSet</VarClipSetId>
          <ConditionFlags />
          <InformationFlags />
        </Item>
      </Maps>
    </Item>
  </ClipSetMaps>

  <VehicleSeatAnimInfos>
    <Item type="CVehicleSeatAnimInfo">
      <Name>SEAT_ANIM_MYBIKE_FRONT</Name>
      <DriveByInfo ref="DRIVEBY_BIKE_SCOOTER" />
      <InsideClipSetMap ref="INSIDE_CLIPSET_MAP_MYBIKE_FRONT" />
      <!-- remaining tags copied from the stock seat anim info you start from -->
    </Item>
  </VehicleSeatAnimInfos>

  <VehicleLayoutInfos>
    <Item type="CVehicleLayoutInfo">
      <Name>LAYOUT_MYBIKE</Name>
      <Seats>
        <Item>
          <SeatInfo ref="SEAT_BIKE_FRONT" />
          <SeatAnimInfo ref="SEAT_ANIM_MYBIKE_FRONT" />
        </Item>
      </Seats>
      <EntryPoints>
        <Item>
          <EntryPointInfo ref="ENTRY_POINT_BIKE_FRONT_LEFT" />
          <EntryPointAnimInfo ref="ENTRY_POINT_ANIM_BIKE_SCOOTER_FRONT_LEFT" />
        </Item>
      </EntryPoints>
      <!-- flags and remaining tags copied from the stock layout -->
    </Item>
  </VehicleLayoutInfos>
</CVehicleMetadataMgr>

Después pon <layout>LAYOUT_MYBIKE</layout> en vehicles.meta. Como el layout tiene su propio nombre, no afecta a ningún otro vehículo del servidor. Así es como el Coil S-Cooter consigue su postura de conducción de pie y los hoverboards su postura: un layout personalizado, clip sets personalizados y diccionarios de animación, sin ningún script de por medio.

Para que esto no se rompa hay dos reglas. Usa nombres que ningún otro resource utilice, ya que los layouts, los asientos y los mapas de clip sets se buscan por nombre en todo el juego. Y asegúrate de que el archivo de layouts se carga antes que vehicles.meta, porque el vehículo busca su layout en el momento en que se registra. FiveM se encarga de ese orden por sí solo, como se explica en la referencia de data_file.

Un ejemplo completo de vehículo con su propio layout está en cómo funciona un hoverboard FiveM sin script.