# Adding a katana (or any custom melee weapon) to FiveM > Add a katana to FiveM as a real add-on melee weapon: weapons.meta based on the machete, archetypes, melee animations, labels and ox_inventory or QBCore items. Source: https://fam-tools.com/guides/fivem-katana-addon-weapon · FAM Tools · published 2026-09-19 · updated 2026-09-19 · about 14 min **Short answer.** The quick route streams a katana model under the machete's file names (`w_me_machette_lr.ydr` and `.ytd`), replacing `WEAPON_MACHETE` for everyone. The proper route adds `WEAPON_KATANA`: a weapons.meta entry copied from `WEAPON_MACHETE` (`FireType` and `DamageType` `MELEE`, `Group` `GROUP_MELEE`, `WheelSlot` `WHEEL_UNARMED_MELEE`, `AmmoInfo ref="NULL"`), a weaponarchetypes.meta entry for `w_me_katana`, a weaponanimations.meta entry that reuses the machete's melee clip sets, a text label, and an inventory item. Tune damage with `SetWeaponDamageModifier`, because vanilla melee entries carry `Damage` 0. ## Key points - Replacing the machete is quick but global; an add-on `WEAPON_KATANA` keeps both. - Copy the whole `WEAPON_MACHETE` entry and change only name, model, slot, pickup and label. - The melee moveset comes from weaponanimations.meta, so reuse the machete's clip sets. - Vanilla melee weapons have `Damage` 0 in weapons.meta; scale damage with `SetWeaponDamageModifier`. - Register the weapon in your inventory, and give it an image and a label. GTA V ships with a machete, a hatchet and a battle axe, but no katana, which is why "fivem katana" is one of the most searched melee topics. There are two ways to get one: put a katana model over an existing melee weapon, or add a proper new weapon called `WEAPON_KATANA`. The first takes five minutes and costs you the machete. The second takes an hour, and this guide walks through every file, using the machete's own definition as the template so the result swings, blocks and sounds right. ## Replace the machete or add a new weapon? *The two ways to get a katana* | Aspect | Replace the machete | Add WEAPON_KATANA | | --- | --- | --- | | Work | Stream two files | Model plus four meta files | | Machete still exists | No | Yes | | Own name and label | No, it is still "Machete" | Yes | | Own inventory item | Shares the machete item | Separate item, weight, price | | Own damage tuning | Shared with the machete | Separate modifier | | Risk | Very low | Meta mistakes break the 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](https://fam-tools.com/guides/fivem-replace-vs-addon-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. *replace resource layout* ```text 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](https://fam-tools.com/guides/blender-sollumz-weapon-export). 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: *Key fields from the machete entry* | Field | Value | Why it matters | | --- | --- | --- | | `FireType` | `MELEE` | It swings instead of firing | | `DamageType` | `MELEE` | Melee damage and reactions | | `Group` | `GROUP_MELEE` | Weapon group for scripts and stats | | `WheelSlot` | `WHEEL_UNARMED_MELEE` | Sits with fists on the weapon wheel | | `AmmoInfo` | `ref="NULL"` | No ammunition | | `AimingInfo` | `ref="UNARMED_TARGETING_RESTRAINTS"` | Melee targeting | | `WeaponRange` | `1.6` | Reach in metres | | `Fx` / `EffectGroup` | `WEAPON_EFFECT_GROUP_MELEE_SHARP` | Blade impact effects | | `WeaponFlags` | includes `AllowMeleeBlock`, `MeleeMachete` | Blocking and blade behaviour | The edited identity lines, and the slot entry at the top of the file, look like this: *data/weapons.meta (excerpt)* ```xml SLOT_KATANA WEAPON_KATANA w_me_katana Katana ``` 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](https://fam-tools.com/guides/fivem-weapons-meta-explained). > **Keep the flags** — Most broken custom melee weapons have a trimmed `WeaponFlags` line. Without `CarriedInHand`, `UsableOnFoot` or `AllowMeleeBlock`, the weapon equips but will not swing or block properly. Copy the machete's flags whole. ## weaponarchetypes.meta The archetype registers the model and tells the game which texture dictionary it uses. One entry is enough: *data/weaponarchetypes.meta* ```xml w_me_katana w_me_katana NULL ``` `modelName` must match the `Model` field in weapons.meta and the `.ydr` file name exactly. More on the file in [weaponarchetypes.meta explained](https://fam-tools.com/guides/fivem-weaponarchetypes-meta). ## 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: *data/weaponanimations.meta (excerpt)* ```xml Cover_Wpn_Melee1h weapons@melee_1h move_strafe_melee_unarmed melee@holster melee@machete@streamed_core MOVE_JUMP@WEAPONS@1H_MELEE@HAMMER ``` 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](https://fam-tools.com/guides/fivem-weaponanimations-meta). 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 *resource layout* ```text katana/ fxmanifest.lua client.lua data/ weapons.meta weaponarchetypes.meta weaponanimations.meta pedpersonality.meta stream/ w_me_katana.ydr w_me_katana.ytd ``` *fxmanifest.lua* ```lua 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' ``` *client.lua* ```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](https://fam-tools.com/guides/fivem-weapon-display-names-addtextentry). ## 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: *client.lua* ```lua 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](https://fam-tools.com/guides/fivem-melee-weapons-guide) 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. *ox_inventory/data/weapons.lua (Weapons table)* ```lua ['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](https://fam-tools.com/guides/qbcore-shared-weapons). Item images are covered in [weapon item images](https://fam-tools.com/guides/fivem-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](https://fam-tools.com/guides/fivem-weapons-on-back) shows how. ## Troubleshooting a custom melee weapon *Common katana problems* | Symptom | Likely cause | | --- | --- | | Invisible in hand, but swings | Model or archetype name mismatch, or the `.ydr` is not in `stream/` | | Held like a pistol | weaponanimations.meta missing or not loaded | | Wrong in first person only | `FirstPerson` animation item missing | | Shows as NULL or a raw name | `AddTextEntry` label missing | | Cannot block | `AllowMeleeBlock` flag removed | | Machete disappears when katana is given | Both use the same `Slot` | | Pink or white blade | Texture dictionary name or shader textures wrong | Texture colour problems are covered in [pink textures](https://fam-tools.com/guides/fivem-weapon-pink-textures); loading problems in general in [the add custom weapons guide](https://fam-tools.com/guides/add-custom-weapons-to-fivem). ## Questions ### Is there a katana in GTA 5? No. The closest vanilla weapons are the machete (`WEAPON_MACHETE`), hatchet and battle axe. A katana is always a replacement model or an add-on weapon. ### How do I add a katana to FiveM? Either stream a katana model as `w_me_machette_lr.ydr`/`.ytd` to replace the machete, or create `WEAPON_KATANA` with weapons.meta, weaponarchetypes.meta and weaponanimations.meta copied from the machete. ### Why does my katana have no damage or deal odd damage? Vanilla melee entries have `Damage` 0 in weapons.meta; melee damage comes from the melee system. Adjust it with `SetWeaponDamageModifier(WEAPON_KATANA, value)` on the client. ### Why does my custom melee weapon use pistol animations? The weaponanimations.meta entry is missing or not loaded with `data_file 'WEAPON_ANIMATIONS_FILE'`. Copy the machete's entries, including the first-person set. ### How do I add the katana to ox_inventory? Add a `WEAPON_KATANA` entry to the `Weapons` table in `data/weapons.lua` with a label, weight and durability, and put `WEAPON_KATANA.png` in `web/images`. ## Related - https://fam-tools.com/guides/fivem-melee-weapons-guide - https://fam-tools.com/guides/add-custom-weapons-to-fivem - https://fam-tools.com/guides/fivem-weaponanimations-meta - https://fam-tools.com/guides/fivem-weaponarchetypes-meta - https://fam-tools.com/guides/fivem-weapon-display-names-addtextentry