Adding a katana (or any custom melee weapon) to FiveM

#Replace the machete or add a new weapon?

A replace is fine for a server that never used the machete. As soon as you want both, or want the item to be called "Katana" in the inventory, go add-on. Replace vs add-on weapons covers the trade-off in general.

The quick route, for completeness: the machete's model is w_me_machette_lr (note the double t and the _lr suffix, from the Lowriders update). Stream a katana model and texture dictionary under exactly those names and every machete in the game becomes a katana.

katana_replace/
  fxmanifest.lua
  stream/
    w_me_machette_lr.ydr
    w_me_machette_lr.ytd

#Preparing the model

You need a katana model you made or have the rights to use, exported as a .ydr with its textures in a .ytd. A few melee-specific points:

• Origin at the grip. The weapon attaches to the hand at the model's origin. Put the origin where the hand closes around the handle, with the blade pointing along the same axis as the vanilla machete. Export the machete from the game files and compare in your 3D tool before exporting yours.
• Reasonable length. Melee hit detection is not driven by the blade mesh, so a very long blade looks like it reaches further than it does. A realistic length avoids arguments.
• Name it once. Use w_me_katana for the model and texture dictionary. The w_me_ prefix matches vanilla melee naming, which keeps the pack easy to read.

Export steps are in the Sollumz export guide. Texture size matters more than people expect on melee weapons, because they are carried and seen up close; 1024 pixels is enough for a blade.

#weapons.meta: start from the machete

Do not write a melee CWeaponInfo from scratch. Copy the complete WEAPON_MACHETE entry from the game files and change only the identity fields. These are the fields that define it as a melee weapon, with the machete's values:

The edited identity lines, and the slot entry at the top of the file, look like this:

<CWeaponInfoBlob>
  <SlotNavigateOrder>
    <Item>
      <WeaponSlots>
        <Item>
          <OrderNumber value="86" />
          <Entry>SLOT_KATANA</Entry>
        </Item>
      </WeaponSlots>
    </Item>
  </SlotNavigateOrder>
  <Infos>
    <Item>
      <Infos>
        <Item type="CWeaponInfo">
          <Name>WEAPON_KATANA</Name>
          <Model>w_me_katana</Model>
          <Audio />
          <Slot>SLOT_KATANA</Slot>
          <DamageType>MELEE</DamageType>
          <FireType>MELEE</FireType>
          <WheelSlot>WHEEL_UNARMED_MELEE</WheelSlot>
          <Group>GROUP_MELEE</Group>
          <AmmoInfo ref="NULL" />
          <AimingInfo ref="UNARMED_TARGETING_RESTRAINTS" />
          <!-- every other field copied unchanged from WEAPON_MACHETE -->
          <PickupHash>PICKUP_WEAPON_MACHETE</PickupHash>
          <HumanNameHash>WT_KATANA</HumanNameHash>
          <StatName>KATANA</StatName>
        </Item>
      </Infos>
    </Item>
  </Infos>
  <Name>Katana</Name>
</CWeaponInfoBlob>

Give the katana its own Slot name. Weapons that share a slot compete for the same place in the ped's loadout, so reusing SLOT_MACHETE can make one weapon replace the other. The excerpt leaves PickupHash pointing at the machete's pickup, because a new pickup type would need its own definitions; with weapon drops disabled on your server it rarely matters, and you can clear it if you prefer. If the machete's CamoDiffuseTexIdxs block is present in your copy, change its key to w_me_katana or remove it. Field meanings are covered in weapons.meta explained.

#weaponarchetypes.meta

The archetype registers the model and tells the game which texture dictionary it uses. One entry is enough:

<CWeaponModelInfo__InitDataList>
  <InitDatas>
    <Item>
      <modelName>w_me_katana</modelName>
      <txdName>w_me_katana</txdName>
      <ptfxAssetName>NULL</ptfxAssetName>
      <lodDist value="500.000000" />
    </Item>
  </InitDatas>
</CWeaponModelInfo__InitDataList>

modelName must match the Model field in weapons.meta and the .ydr file name exactly. More on the file in weaponarchetypes.meta explained.

#weaponanimations.meta: borrowing the machete's moveset

This file is what makes the katana move like a blade instead of a pistol. Copy the machete's WEAPON_MACHETE items, both the one under the Default set and the one under FirstPerson, and rename the key. The lines that give the one-handed blade moveset are:

<Item key="WEAPON_KATANA">
  <CoverWeaponClipSetHash>Cover_Wpn_Melee1h</CoverWeaponClipSetHash>
  <MotionClipSetHash>weapons@melee_1h</MotionClipSetHash>
  <MotionStrafingClipSetHash>move_strafe_melee_unarmed</MotionStrafingClipSetHash>
  <WeaponClipSetHash>melee@holster</WeaponClipSetHash>
  <MeleeClipSetHash>melee@machete@streamed_core</MeleeClipSetHash>
  <JumpUpperbodyClipSetHash>MOVE_JUMP@WEAPONS@1H_MELEE@HAMMER</JumpUpperbodyClipSetHash>
  <!-- remaining fields copied from WEAPON_MACHETE -->
</Item>

If you want a two-handed stance instead, use the baseball bat as the template: copy WEAPON_BAT's animation items and add the TwoHanded flag from its weapons.meta entry. Mixing a two-handed animation set with one-handed flags produces hands that float off the handle. Skipping the FirstPerson item makes the katana look wrong in first person, which is the most common complaint about katana packs; see weaponanimations.meta explained.

The machete template also ships a pedpersonality.meta, which lists the weapon under holster clips such as UNHOLSTER_1H and UNHOLSTER_2H_MELEE. Add WEAPON_KATANA next to the machete there if the draw looks abrupt.

#The resource and fxmanifest

katana/
  fxmanifest.lua
  client.lua
  data/
    weapons.meta
    weaponarchetypes.meta
    weaponanimations.meta
    pedpersonality.meta
  stream/
    w_me_katana.ydr
    w_me_katana.ytd

fx_version 'cerulean'
game 'gta5'

files {
    'data/weapons.meta',
    'data/weaponarchetypes.meta',
    'data/weaponanimations.meta',
    'data/pedpersonality.meta',
}

data_file 'WEAPONINFO_FILE' 'data/weapons.meta'
data_file 'WEAPON_METADATA_FILE' 'data/weaponarchetypes.meta'
data_file 'WEAPON_ANIMATIONS_FILE' 'data/weaponanimations.meta'
data_file 'PED_PERSONALITY_FILE' 'data/pedpersonality.meta'

client_script 'client.lua'

CreateThread(function()
    AddTextEntry('WT_KATANA', 'Katana')
    SetWeaponDamageModifier(`WEAPON_KATANA`, 1.2)
end)

Start the resource before your inventory in server.cfg. The label comes from the HumanNameHash in weapons.meta, as explained in weapon display names.

#Damage and balance

Vanilla melee weapons have Damage set to 0 in their weapons.meta entries; how hard they hit is handled by the melee system rather than a bullet damage value. That means raising Damage in your copy is not the way to make the katana stronger. Use the per-weapon modifier on the client, as the melee guide does for bats and fists:

SetWeaponDamageModifier(`WEAPON_KATANA`, 1.2)            -- 20% above the machete
SetPlayerMeleeWeaponDamageModifier(PlayerId(), 0.8)     -- all melee, if you want it softer overall

Think about what a katana should do on your server. On a roleplay server, a sword that kills in two swings ends scenes as quickly as a pistol, and it is silent. Many servers keep it close to the machete, make it heavy in the inventory, and treat it as a rare item. Melee weapons and fist fights covers the global melee settings.

#Adding it to ox_inventory or QBCore

The weapon exists once the resource starts; players only get one if your inventory knows about it.

['WEAPON_KATANA'] = {
    label = 'Katana',
    weight = 1500,
    durability = 0.1,
},

Melee weapons in ox_inventory have no ammoname, exactly like the vanilla machete entry. Add an image at ox_inventory/web/images/WEAPON_KATANA.png. For QBCore, add a lowercase weapon_katana item with type = 'weapon' to shared/items.lua and a matching entry in shared/weapons.lua; field details are in QBCore shared weapons. Item images are covered in weapon item images.

To show the sheathed katana on the player's back when it is not drawn, add it to a back-weapon script with its own offset; weapons on back shows how.

#Troubleshooting a custom melee weapon

Texture colour problems are covered in pink textures; loading problems in general in the add custom weapons guide.