vehiclelayouts.meta explicado: assentos, pontos de entrada e animações

Um layout é uma lista nomeada de assentos e pontos de entrada. Cada assento junta uma definição de assento (qual bone, quais vizinhos) com uma definição de animação de assento (quais clips tocam nele). Cada ponto de entrada junta uma definição de porta com uma definição de animação de entrada. Tudo é referenciado pelo nome, então um layout pode reaproveitar partes dos layouts originais.

Este é o LAYOUT_STANDARD original, o padrão dos carros, resumido aos dois assentos da frente:

<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>

O elemento raiz é CVehicleMetadataMgr. Ele guarda uma lista para cada tipo de definição. Um arquivo só precisa das listas em que adiciona algo. Os nomes que ele referencia mas não define vêm dos arquivos do próprio jogo.

Lista	Tipo do item	O que define
VehicleLayoutInfos	CVehicleLayoutInfo	O layout: assentos, pontos de entrada, flags.
VehicleSeatInfos	CVehicleSeatInfo	Um assento: bone, links de troca de assento, flags do assento.
VehicleSeatAnimInfos	CVehicleSeatAnimInfo	Animações usadas enquanto se está em um assento, configuração de drive-by.
VehicleEntryPointInfos	CVehicleEntryPointInfo	Uma entrada: bone da porta, lado, a quais assentos ela dá acesso.
VehicleEntryPointAnimInfos	CVehicleEntryPointAnimInfo	Animações de entrar e sair por um ponto de entrada.
ClipSetMaps	CClipSetMap	Listas nomeadas de clip sets para as quais os anim infos apontam.
VehicleDriveByInfos, VehicleDriveByAnimInfos		Mirar e atirar de um assento.
AnimRateSets, BicycleInfos, VehicleExtraPointsInfos, EntryAnimVariations, VehicleCoverBoundOffsetInfos, VehicleExplosionInfos		Velocidades de animação, pedalada de bicicleta, posições extras de entrada, variações de entrada, configurações de cobertura e de explosão.

Campo	Significado
Name	O nome do layout usado no campo layout do vehicles.meta.
Seats	Um item por assento, cada um com uma referência SeatInfo e uma SeatAnimInfo.
EntryPoints	Um item por entrada, cada um com uma referência EntryPointInfo e uma EntryPointAnimInfo.
LayoutFlags	Flags de comportamento separadas por espaço (veja abaixo).
BicycleInfo	Configuração de pedalada para bicicletas, senão NULL.
AnimRateSet	Conjunto de velocidades de animação para entrar e sair.
HandsUpClipSetId	Clip set da pose de mãos para cima (padrão busted_vehicle_std).
SteeringWheelOffset	Posição do volante usada para posicionar as mãos (padrão 0, 0.35, 0.32).
FirstPersonAdditiveIdleClipSets, FirstPersonRoadRageClipSets	Clip sets de idle e de road rage em primeira pessoa.

Algumas das flags de layout, com o que os nomes dizem: NoDriver, StreamAnims, WarpIntoAndOut, BikeLeansUnlessMoving, UseSteeringWheelIk, UseLeanSteerAnims, MustCloseDoor, AutomaticCloseDoor, DisableJackingAndBusting, UseDoorOscillation, WarpInWhenStoodOnTop. O schema define 32 no total. Comece pelas flags do layout original mais próximo do seu veículo e mude uma de cada vez.

Um assento fica preso a um bone do modelo do veículo, e um ponto de entrada a um bone de porta. Se o modelo não tiver o bone que a definição indica, aquele assento ou aquela porta não tem como funcionar. Estes são o assento do motorista e a porta do motorista originais de um carro:

<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 em que o ped fica preso. Carros usam seat_dside_f, seat_pside_f, seat_dside_r e seat_pside_r (lado do motorista e lado do passageiro, frente e trás).
ShuffleLink	Assento para o qual o ped desliza, por exemplo do passageiro para o motorista.
RearSeatLink	O assento atrás deste.
SeatFlags	Por exemplo IsFrontSeat, IsIdleSeat, NoIndirectExit, KeepOnHeadProp, FakeSeat.
DoorBoneName, DoorHandleBoneName	Bones da porta e da maçaneta até onde o ped anda e estende a mão, por exemplo door_dside_f e handle_dside_f. Ficam vazios em veículos sem portas.
WindowId	FRONT_LEFT, FRONT_RIGHT, REAR_LEFT, REAR_RIGHT, MID_LEFT, MID_RIGHT, FRONT_WINDSCREEN, REAR_WINDSCREEN ou INVALID.
VehicleSide	SIDE_LEFT, SIDE_RIGHT ou SIDE_REAR.
AccessableSeats	Assentos que podem ser alcançados por este ponto de entrada. A grafia com a é o nome real da tag.

As animações chegam a um assento por quatro ligações. Cada ligação é uma busca por nome, então uma quebra em qualquer ponto da cadeia deixa você com a animação original ou sem nenhuma.

1. O arquivo de animação, um clip dictionary (.ycd), vai na pasta stream do resource.
2. Um clip set no clip_sets.xml dá a esse dicionário um nome de clip set. Ele é carregado com data_file 'CLIP_SETS_FILE'.
3. Um CClipSetMap no vehiclelayouts.meta lista esse nome de clip set em ClipSetId.
4. Um seat anim info aponta para o map com InsideClipSetMap (clips tocados enquanto sentado), e um entry point anim info com EntryClipSetMap, ExitClipSetMap e 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>

O jogo pede clips a um clip set por nomes fixos, então um dicionário personalizado mantém os nomes de clip do dicionário original que ele substitui e só muda o movimento dentro deles.

Crie um layout com um nome novo, copie o layout original que o veículo usaria normalmente e substitua só as referências que você quer mudar. Tudo o que você não redefine continua apontando para as definições originais.

<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>

Depois coloque <layout>LAYOUT_MYBIKE</layout> no vehicles.meta. Como o layout tem nome próprio, nenhum outro veículo do servidor muda. É assim que o Coil S-Cooter ganha a pose de pilotagem em pé e os hoverboards a postura deles: um layout personalizado, clip sets e dicionários de animação personalizados, sem nenhum script.

Duas regras mantêm isso funcionando. Use nomes que nenhum outro resource usa, já que layouts, assentos e clip set maps são buscados pelo nome no jogo inteiro. E o arquivo de layout tem que carregar antes do vehicles.meta, porque o veículo busca seu layout na hora em que é registrado. O FiveM cuida dessa ordem sozinho, como explicado na referência de data_file.

Um exemplo completo de veículo com layout próprio está em como um hoverboard FiveM funciona sem script.