DayZ Firearm Modding — the ENTITY side

A custom firearm in DayZ extends the vanilla Weapon chain — you do NOT build one from EntityAI. Inheriting the config base of the vanilla/pack weapon whose ammo, mags, recoil, sounds and anims you want gives all of that for free; you author only the mesh, the .p3d part contract, the config deltas, and the import transform. This skill is the entity layer: the .p3d selection + memory-point contract, the bone-remap glue, the CfgWeapons config, and the model-path / winding / serve-binarized invariants that gate whether the build loads at all.

FRONTIER — this skill is NOT weapon animation. Grip / hand pose / ADS line, and the MOTION of the bolt / trigger / reload / fire / jam-unjam (the .anm / .asi authoring) belong to dayz-animation-pipeline (weapon-in-hands.md, weapon-anim-*). This skill owns which selections and points must EXIST and cover the right part, and which selection maps to which bone — not how they move. The delegation map at the end is the exact split.

Distilled from two closed, in-game-verified projects: A6_MK47 (AI-mesh 7.62×39 rifle, A6_MK47_dev\, v12c [VERIFIED in-game] 2026-06-11) — import + model-path + winding; and A6_SR2M (user-mesh 9×19 SMG, A6_SR2M\ + A6_SR2M_dev\, [VERIFIED in-game] 2026-06-30) — bone-remap, mis-authored-selection detection + repaint, casing side, root-scope Mode_*.

PREFLIGHT — invariants to check BEFORE the first in-game cycle (not after the fail)

Each was won the hard way on one of the two projects. Front-load them offline; full detail behind each pointer. Firearm test cycles are as expensive as any DayZ rebuild — a preflight pass is nearly free.

1. W-BUILD1 — model= must point at the real in-PBO path (data\), built with -Clean. [VERIFIED in-game] MK47. config.cpp model= pointed at PBO root while the .p3d lived under data\; a build without -Clean dragged a stowaway MLOD at the root → THAT was the model the engine loaded, invalidating every offline winding/normals measurement. Fix = model="\<Mod>\data\<wpn>.p3d"
   • -Clean rebuild. → LL-145, import-rule-v4.md §"model-path".
2. W-BUILD2 — serve BINARIZED; test A6-family mods with the RETAIL exe. [VERIFIED in-game] MK47. The winding/normals contract is only correct on the binarized ODOL (binarize flips winding); a diag-pair / MLOD-served build measures the wrong thing. Also the A6 weapon pack uses brace-less syntax that DayZDiag strict-compile REJECTS → RETAIL exe, not DayZDiag. → import-rule-v4.md, dayz-test-ingame.
3. W-SEL1 — every bone-remapped selection must SPATIALLY cover its real part before you trust it. [VERIFIED in-game] SR2M. The bolt selection was authored onto the barrel (X[−0.19,−0.09], in front of the chamber), not the bolt; AddItemBoneRemap("bolt") would have slid the barrel — "the bolt didn't move, not even conceptually." Caught OFFLINE by comparing the selection centroid to anatomy (a bolt sits BEHIND the chamber). → p3d-selection-contract.md §"mis-authored selection".
4. W-MEM1 — casing eject side is weapon-frame-dependent; read the reference, do not assume. [VERIFIED in-game] SR2M. nabojnicestart/nabojniceend set the shell-eject side; SR2M was on +Z (wrong, ejected into the receiver), flipped to −Z, confirmed correct. → p3d-selection-contract.md.
5. W-MEM2 — a weapon .p3d carries NO hand/grip memory points. [VERIFIED-vanilla] akm.p3d memory LOD. Grip is set by the player .anm IK pose + geometric parity, NOT by points in the weapon — that is the ANIM boundary. → p3d-selection-contract.md, dayz-animation-pipeline.
6. W-CFG1 — Mode_SemiAuto / Mode_FullAuto must be forward-declared at ROOT config scope, before class CfgWeapons. [VERIFIED in-game] SR2M. Forward-declaring Mode_FullAuto INSIDE CfgWeapons makes an empty stub without autoFire=1 → the mode is dropped → weapon stuck in single. → cfgweapons-contract.md §"root-scope Mode_*".
7. W-STAGING1 — (desde 1.30 Exp) a firearm script under 4_World/Entities/Firearms/ does NOT imply a packed .p3d or CfgWeapons class. [VERIFIED-vanilla] 1.30.164014. SCARL, Luger, LeeEnfield, MP18 (and P1907_Bayonet) have scripts + IK registrations; their weapon PBOs have no matching model/config. NEVER debinarize them from this experimental client as a parity reference — inherit a shipped peer (SCARH / a 1.29 pistol / CZ527 / CZ61). → dayz-1-30-weapons.md.

Memory-point sanity (each was a real AI-mesh bug on MK47): usti hlavne/konec hlavne share Y and Z (level bore); bolt_axis parallel to bore; eject direction within ~25° of the reference; eye height over bore ≈ reference. → p3d-selection-contract.md §"memory-point sanity".

PARITY-FIRST — debinarize the vanilla weapon you inherit, diff against it

The through-line of both projects. Pick the vanilla/pack weapon whose behavior you want (AKM for AK-pattern, AKS74U/PM73 for an SMG), debinarize it (external ODOL→MLOD converter), read its memory LOD and its config, and match: named selections present, memory points shaped the same, config base chosen for its ammo / mags / recoil / sounds / anims. Every preflight item above falls out of this one diff instead of error-by-error in-game. → p3d-selection-contract.md, cfgweapons-contract.md.

(hasta 1.29: that vanilla weapon is always in the matching weapons_*.pbo.) (desde 1.30 Exp: W-STAGING1 — scripts for SCARL / Luger / LeeEnfield / MP18 are not a licence to unpack those classnames from this build. Debinarize SCARH\ScarH.p3d (listed in work\pbo-listings\exp__Addons__weapons_firearms.txt) or another packed peer. Details: dayz-1-30-weapons.md.)

QUICK TRIAGE

DELEGATION MAP — ANIM vs ENTITY, and the generic-pipeline hand-offs

CITE-THEN-VERIFY

Weapon config fields and named selections are easy to half-remember, and the vanilla firearm hierarchy is NOT a straight line (RifleBoltFree_Base extends Rifle_Base, but BoltActionRifle_Base and Pistol_Base extend Weapon_Base DIRECTLY — see cfgweapons-contract.md). Before writing a class name, field, or selection, grep it in vanilla (P:\scripts\4_world\entities\firearms\, a debinarized vanilla .p3d) or the cited references, and keep the provenance labels the references use: [VERIFIED in-game] (a real in-game test in a project handoff) vs [VERIFIED-vanilla] (read off disk) vs [UNVERIFIED] (inferred, not confirmed). Anchor every new weapon lesson to a real mod with path:line, never memory.

(hasta 1.29: pistol stable states were constructed with PistolAnimState.* constants — stable-1.29 Pistol_Base.c:203-212.) (desde 1.30 Exp: InitStateMachine() passes GetDischargedPistolAnimState() / GetChargedPistolAnimState() / GetOpenPistolAnimState() / GetJammedPistolAnimState() — exp\scripts\scripts\4_World\Entities\Firearms\Pistol_Base.c:203-212. Override those getters on an atypical pistol (Luger: charged→DEFAULT, jammed→CLOSED_CHARGED in Pistol\Luger.c:8-21). Do not duplicate the Pistol_CLO_* FSM. → dayz-1-30-weapons.md.)

AMMO CLASSIFICATION SERVER-SIDE (added 2026-08-13, LFPowerGrid turret)

Reading a cartridge ROLE (pistol / intermediate / full-power / shell / arrow) at runtime — needed by any system that must behave differently per ammo class WITHOUT a classname whitelist (turrets, per-class ballistics, loot logic, scaling that must also work for modded weapons):

• enum CartridgeType { None=0, Pistol=1, Intermediate=2, FullPower=3, Shell=4, Arrow=5 } — P:\scripts\4_world\entities\itembase\magazine\magazine.c:3-11 [VERIFIED-vanilla]
• The class lives on the MAGAZINE/pile config, not on CfgAmmo: g_Game.ConfigGetInt("CfgMagazines " + pileType + " iconCartridge") — magazine.c:32 [VERIFIED-vanilla]. Guard with ConfigIsExisting("CfgMagazines " + pileType) first (magazine.c:29); a modded pile that omits the key yields 0 (None), so choose an explicit fallback band rather than trusting that zero.
• Two paths, and the guard covers only one. The constructor PRE-loads Magazine.m_AmmoData inside if (!g_Game.IsDedicatedServer()) (magazine.c:45-64), but the static accessor Magazine.GetAmmoData(classname) fills the map LAZILY with no such guard (magazine.c:117-132) [VERIFIED-vanilla] — so it does work server-side. The real caveat is allocation, not availability: the first miss constructs an AmmoData (:123-125), so never take that path inside a hot loop. Read it once on an attachment event and cache it yourself. (Corrects an earlier version of this entry that claimed the map is never populated on a dedicated server.)
• Gate on IsAmmoPile() when you mean loose rounds, not magazines. Object.IsAmmoPile() returns false by default (3_game\entities\object.c:577-580) and Ammunition_Base overrides it to true (4_world\entities\itembase\magazine\ammunitionpiles.c:27-30) [VERIFIED-vanilla]. Detachable magazines do NOT declare iconCartridge, so any per-cartridge-class logic must reject them first or it silently classifies every mag as None.
• iconCartridge coverage is NOT total in vanilla. Ammunition_Base sets it to 0, and at least five concrete scope=2 ammo classes resolve to 0/None (CupidsBolt, RPG7_HE, RPG7_AP, LAW_HE, GrenadeM4). Any band table needs an explicit policy for None, and must separate "0 declared" from "key absent" — what ConfigGetInt returns for a missing path is undocumented, so probe with ConfigIsExisting first.
• You can read binarized vanilla configs without a P:\DZ tree: run Mikero/BI CfgConvert -txt over the installed game's PBOs (…\Steam\steamapps\common\DayZ\Addons\weapons_ammunition.pbo, weapon_magazines.pbo). This is how the coverage numbers above were established on a machine with no unpacked vanilla tree — reach for it before declaring a config claim unverifiable.
• Cartridge -> ammo type for the damage system: AmmoTypesAPI.MagazineTypeToAmmoType(magType, out ammoType) — P:\scripts\3_game\global\ammotypes.c:14, used by vanilla in weapon_base.c:848 [VERIFIED-vanilla]. Do not hand-roll a CfgMagazines <t> ammo lookup. (up to 1.29: those line numbers.) (since 1.30 Exp: MagazineTypeToAmmoType is exp\scripts\scripts\3_Game\Global\AmmoTypes.c:26; vanilla Weapon_Base.c:840. GetExplosionParticleID is gone — MUST call AmmoTypesAPI.GetExplosiveEffectData(ammoName, surfaceName) and read m_ParticleID / m_SoundSetName on ExplosiveEffectData. → dayz-1-30-weapons.md.)
• A cartridge damage profile is readable BEFORE firing: ConfigGetFloat("CfgAmmo " + ammoType + " DamageApplied Health damage") (also Blood damage, Shock damage) — P:\scripts\4_world\entities\dayzplayerimplementfalldamage.c:261-263 [VERIFIED-vanilla]. This is how a mod caps absurd modded ammo without a whitelist.
• iconCartridge is nominally a UI icon field reused as the cartridge class: confirm per-pile coherence against a debinarized config before shipping balance that depends on it. [UNVERIFIED]

DayZ 1.30 Exp (build 1.30.164014)

What changes, what breaks, and the migration checklist. Full citations and [EXACT] blocks: dayz-1-30-weapons.md. Recoil curves and Luger/LeeEnfield bone remaps: bone-remap.md, cfgweapons-contract.md.

What changes

• Four firearm scripts (SCARL_Base : SCARH_Base, Luger_Base, LeeEnfield_Base, MP18_Base) plus P1907_Bayonet and mag stubs — scripts and (for Luger/LeeEnfield) extra AddItemBoneRemap arrays; IK .asi/.anm packed; no CfgWeapons / weapon .p3d in this experimental PBO set (W-STAGING1).
• Pistol FSM anim IDs are virtual getters on Pistol_Base (Pistol_Base.c:611-629, wired at :203-212).
• OpenBolt_Base.SetActions() adds FirearmActionDetachMagazine (OpenBolt_Base.c:388).
• Weapon_Base.EEItemDetached calls ValidateAndRepair() when the detached item is a magazine (:1121).
• Explosion FX: ExplosiveEffectData + GetExplosiveEffectData(string, string) replace GetExplosionParticleID. ExplosivesBase.SetParticleExplosion / AddExplosionEffectForSurface are [Obsolete("1.30: Handled in AmmoTypes instead")].
• Attach mag action requires TestAttachMagazine(...) (FirearmActionAttachMagazine.c:256).
• Chamber helper uses LocalAcquireCartridgeEx (weapon_utils.c:9).

What breaks for a 1.29 weapon mod

1. Compile error if you still call AmmoTypesAPI.GetExplosionParticleID.
2. Reload never starts if TestAttachMagazine is too strict/wrong on a custom muzzle.
3. Open-bolt mag-detach workarounds fight the new AddAction(FirearmActionDetachMagazine).
4. Spawning SCARL / Luger / LeeEnfield / MP18 / Mag_Luger_8Rnd / Mag_MP18_Drum32Rnd from types/traders fails — no config class. [CHANGELOG] SoundHitType / GetSoundHitType() are not in Enforce SurfaceInfo.c on this build (T189758); do not call them from weapon scripts.

Migration checklist

• Replace explosion-particle lookups with GetExplosiveEffectData(ammoType, surfaceType).
• Drop SetParticleExplosion / script surface-particle maps; set particle on CfgAmmo.
• Atypical pistols: override Get*PistolAnimState(), keep the stock pistol FSM.
• Confirm TestAttachMagazine for custom mag/bolt states.
• Use LocalAcquireCartridgeEx in custom chamber helpers.
• Parity-first: debinarize a packed peer, not the 1.30 staged classnames.
• Do not add staged classnames to types.xml until Bohemia ships CfgWeapons + .p3d.