vehiclelayouts.meta explained: seats, entry points and animations

A layout is a named list of seats and entry points. Each seat pairs a seat definition (which bone, which neighbours) with a seat animation definition (which clips play in it). Each entry point pairs a door definition with an entry animation definition. Everything is referenced by name, so one layout can reuse pieces from stock layouts.

This is the stock LAYOUT_STANDARD, the default for cars, shortened to its two front seats:

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

The root element is CVehicleMetadataMgr. It holds one list per kind of definition. A file only needs the lists it adds something to. Names it references but does not define are taken from the game's own files.

List	Item type	What it defines
VehicleLayoutInfos	CVehicleLayoutInfo	The layout: seats, entry points, flags.
VehicleSeatInfos	CVehicleSeatInfo	A seat: bone, shuffle links, seat flags.
VehicleSeatAnimInfos	CVehicleSeatAnimInfo	Animations used while in a seat, drive-by setup.
VehicleEntryPointInfos	CVehicleEntryPointInfo	A way in: door bone, side, which seats it reaches.
VehicleEntryPointAnimInfos	CVehicleEntryPointAnimInfo	Animations for getting in and out at one entry point.
ClipSetMaps	CClipSetMap	Named lists of clip sets that the anim infos point to.
VehicleDriveByInfos, VehicleDriveByAnimInfos		Aiming and shooting from a seat.
AnimRateSets, BicycleInfos, VehicleExtraPointsInfos, EntryAnimVariations, VehicleCoverBoundOffsetInfos, VehicleExplosionInfos		Animation speeds, bicycle pedalling, extra entry positions, entry variations, cover and explosion setups.

Field	Meaning
Name	The layout name used in the layout field of vehicles.meta.
Seats	One item per seat, each with a SeatInfo and a SeatAnimInfo reference.
EntryPoints	One item per way in, each with an EntryPointInfo and an EntryPointAnimInfo reference.
LayoutFlags	Space-separated behaviour flags (see below).
BicycleInfo	Pedalling setup for bicycles, otherwise NULL.
AnimRateSet	Animation speed set for entering and leaving.
HandsUpClipSetId	Clip set for the hands-up pose (default busted_vehicle_std).
SteeringWheelOffset	Position of the steering wheel used for hand placement (default 0, 0.35, 0.32).
FirstPersonAdditiveIdleClipSets, FirstPersonRoadRageClipSets	First-person idle and road-rage clip sets.

Some of the layout flags, with what their names say: NoDriver, StreamAnims, WarpIntoAndOut, BikeLeansUnlessMoving, UseSteeringWheelIk, UseLeanSteerAnims, MustCloseDoor, AutomaticCloseDoor, DisableJackingAndBusting, UseDoorOscillation, WarpInWhenStoodOnTop. The schema defines 32 in total. Start from the flags of the stock layout closest to your vehicle and change one at a time.

A seat is bound to a bone in the vehicle model, and an entry point to a door bone. If the model does not have the bone the definition names, that seat or door cannot work. These are the stock driver seat and driver door of a car:

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

Field	Meaning
SeatBoneName	Bone the ped is attached to. Cars use seat_dside_f, seat_pside_f, seat_dside_r and seat_pside_r (driver side and passenger side, front and rear).
ShuffleLink	Seat a ped slides over to, for example from passenger to driver.
RearSeatLink	The seat behind this one.
SeatFlags	For example IsFrontSeat, IsIdleSeat, NoIndirectExit, KeepOnHeadProp, FakeSeat.
DoorBoneName, DoorHandleBoneName	Door and handle bones the ped walks to and reaches for, for example door_dside_f and handle_dside_f. Left empty on vehicles without doors.
WindowId	FRONT_LEFT, FRONT_RIGHT, REAR_LEFT, REAR_RIGHT, MID_LEFT, MID_RIGHT, FRONT_WINDSCREEN, REAR_WINDSCREEN or INVALID.
VehicleSide	SIDE_LEFT, SIDE_RIGHT or SIDE_REAR.
AccessableSeats	Seats that can be reached from this entry point. The spelling with an a is the real tag name.

Animations reach a seat through four links. Each link is a name lookup, so a break anywhere in the chain leaves you with the stock animation or none at all.

1. The animation file, a clip dictionary (.ycd), goes in the resource's stream folder.
2. A clip set in clip_sets.xml gives that dictionary a clip set name. It is loaded with data_file 'CLIP_SETS_FILE'.
3. A CClipSetMap in vehiclelayouts.meta lists that clip set name in ClipSetId.
4. A seat anim info points to the map with InsideClipSetMap (clips played while seated), and an entry point anim info with EntryClipSetMap, ExitClipSetMap and 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>

The game asks a clip set for clips by fixed names, so a custom dictionary keeps the clip names of the stock dictionary it replaces and only changes the motion inside them.

Create a layout with a new name, copy the stock layout the vehicle would normally use, and replace only the references you want to change. Everything you do not redefine keeps pointing at the stock definitions.

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

Then set <layout>LAYOUT_MYBIKE</layout> in vehicles.meta. Because the layout has its own name, no other vehicle on the server is affected. This is how the Coil S-Cooter gets its stand-up riding pose and the hoverboards their stance: a custom layout, custom clip sets and animation dictionaries, with no script involved.

Two rules keep this working. Use names that no other resource uses, since layouts, seats and clip set maps are looked up by name across the whole game. And make sure the layout file is loaded before vehicles.meta, because the vehicle looks its layout up when it is registered. FiveM takes care of that order by itself, as explained in the data_file reference.

A full example of a vehicle built on its own layout is in how a FiveM hoverboard works without a script.